simplified-shopify-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean Schulz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# Simplified Shopify CLI
+
+Short Shopify theme commands with store aliases you configure in a JSON dotfile.
+Installing the package provides **`sd`, `sp`, `sl`, `si`, `spl`, `spa`, `sc`, `sf`,
+and `lo` directly**. The `sshop` command remains available for compatibility.
+
+This is the **0.1.0 release**, licensed under MIT, with no runtime
+dependencies. Source: [deanschulz4/Shopify-CLI-Simplified](https://github.com/deanschulz4/Shopify-CLI-Simplified).
+
+Install from npm using the instructions below. See [release notes and verification](docs/RELEASING.md).
+
+## Install
+
+Requires Node.js 22.12+ and Shopify CLI on your PATH. Authentication remains
+managed by Shopify CLI. Install Shopify CLI if you do not already have it:
+
+```sh
+npm install -g @shopify/cli
+```
+
+Install the published package (including zsh on macOS):
+
+```sh
+npm install -g simplified-shopify-cli
+shelp
+```
+
+To install from a source checkout instead, run `npm install -g .` from the project directory.
+
+Or try it without a global installation:
+
+```sh
+node bin/sshop.js --help
+node bin/sshop.js --config examples/sshop.example.json sd demo "My Theme" --dry-run
+```
+
+## Configure your stores
+
+Create a personal config usable from any project:
+
+```sh
+sshop init --global
+sshop stores add demo example-store --global
+sshop stores add sandbox example-sandbox.myshopify.com --global
+sshop stores
+```
+
+This creates `~/.sshop.json`. For project-specific configuration, run the same
+commands without `--global` from the project root. Example:
+
+```json
+{
+  "version": 1,
+  "stores": {
+    "demo": "example-store.myshopify.com",
+    "sandbox": "example-sandbox.myshopify.com"
+  },
+  "defaultStore": "sandbox",
+  "defaults": {
+    "nodelete": true,
+    "themeEditorSync": true
+  }
+}
+```
+
+Store values accept Shopify store prefixes, full `myshopify.com` domains, or
+their HTTPS URLs. Custom storefront domains are not accepted. Config is data;
+it cannot contain shell commands. Keep authentication tokens in Shopify's normal
+authentication flow or environment variables, outside this file.
+
+### Config precedence
+
+1. Built-in defaults: preserve unmatched local files during pull; enable Theme Editor sync during dev.
+2. Personal `~/.sshop.json`.
+3. The nearest `.sshop.json`, searching upward from your current directory.
+
+Project aliases override personal aliases with the same name. Other aliases
+remain available. Set `defaultStore` to `null` to clear an inherited default.
+With no configured default or explicit store, Shopify resolves its own store.
+
+`sshop --config /path/to/config.json …` or `SSHOP_CONFIG` selects a single isolated
+config instead of merging. An explicit missing config is an error.
+`sshop config` shows the effective settings and exact source files.
+
+Writes always target the current directory, or the personal file with `--global`,
+or the explicitly selected file. They never silently modify an ancestor's config.
+`init` refuses to overwrite an existing file. `stores add` explicitly replaces
+an existing alias; `stores remove ALIAS` removes it only from the selected file.
+Removing a project override can expose the personal alias again.
+
+Add `.sshop.json` to each theme project's `.gitignore` if it contains personal
+store mappings. This package excludes local configuration and legacy source
+from its distributable archive.
+
+## Shopify command cheat sheet
+
+### Rules
+
+- Run theme commands from your theme project folder.
+- Replace `<store_abr>` with your configured store abbreviation.
+- Select the current store once with `si <store_abr>`. After it succeeds, omit `<store_abr>` in commands such as `sl`, `sd "My Theme"`, `sp -p`, `sp -d`, and `si -j`.
+- Run `si` to check the current store; specify another abbreviation to switch.
+- Store aliases are still required when adding or removing aliases.
+
+### Flags
+
+- `-g` = `--global` for `sinit`, `sstores add/remove`, and `simport`.
+- `-d` = `--development` for `sp`, `spl`, `spa`, and `si`.
+- Both long and short forms work.
+
+### Important
+
+- A configured `defaultStore` overrides the remembered Shopify store. `si` does not change `defaultStore`; clear it or set it to the intended store.
+- The selected store is not permanently bound to your project.
+- `si --dry-run` does not select a store.
+- `sinit` creates configuration only.
+
+This follows Shopify's [connecting-to-a-store behavior](https://shopify.dev/docs/storefronts/themes/tools/cli#connecting-to-a-store).
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `si <store_abr>` | Select the current Shopify store and show theme information; omit `<store_abr>` in later theme commands |
+| `sl` | List all themes |
+| `sd "Theme Name"` or `sd Theme_Name` | Start development on a named theme with editor sync |
+| `sd` | Start development using a Shopify development theme |
+| `sp "Theme Name"` or `sp theme_name` | Pull a named theme; preserve unmatched local files |
+| `sp` | Pull the live theme; preserve unmatched local files |
+| `sp -p` | Pull only live template/config JSON |
+| `spl "My Theme"` | Pull only template/config JSON from a named theme |
+| `spa` | Pull the live theme; may delete unmatched local files |
+| `sp -d` | Pull the development theme |
+| `sc` | Check theme code for issues |
+| `sf` | Automatically fix supported theme issues |
+| `lo` | Log out of Shopify |
+
+### Store aliases and setup
+
+| Command | What it does |
+| --- | --- |
+| `sstores` | List available store aliases |
+| `sstores add <store_abr> example-store -g` | Add/update a personal store alias |
+| `sstores remove <store_abr> -g` | Remove a personal store alias |
+| `sconfig` | Show effective settings and config locations |
+| `sinit` | Create a project-specific config |
+| `sinit -g` | Create a personal config; refuses to overwrite |
+| `simport ./base_custom_cli.sh -g` | Import aliases from the original file |
+| `shelp` | Show command help |
+
+### Useful options
+
+| Example | What it does |
+| --- | --- |
+| `sd "My Theme" --dry-run` | Preview the command without running Shopify |
+| `sd -s <store_abr> -t "My Theme"` | Explicitly select store and theme |
+| `sd -p 9293` | Use a different development port |
+| `sl -j` | Return the theme list as JSON |
+| `sd --config "./custom.json"` | Use a specific configuration file |
+
+### Remember
+
+- Quotes are required for theme names containing spaces. Use straight quotes (`"`) when copying commands into your terminal.
+- Pull (`sp`) overwrites matching local files. Preserving unmatched files does not prevent existing files from being overwritten.
+- Dev (`sd`) uploads and continuously syncs changes to the selected remote theme.
+- `sd <store_abr> -p 9293` sets the development port; `sp <store_abr> -p` pulls only template/config JSON.
+- `si <store_abr> -j` returns theme information as JSON; `sl <store_abr> -j` returns the theme list as JSON.
+- `sf` modifies local files. Use `--dry-run` to inspect command targeting before running Shopify.
+
+### Argument handling and compatibility
+
+All commands above work without an `sshop` prefix. The prefixed equivalents
+remain supported, for example `sshop dev`, `sshop pull`, and `sshop sd`.
+
+A single positional argument to `sd`/`sp` is a store if it matches a configured
+alias or looks like a URL/domain; otherwise it is a theme. With two positional
+arguments, they mean store and theme. Use `--store` for an unmapped prefix with
+no theme; use `--theme` when a theme name matches an alias.
+
+Wrapper flags use separate values (`--store demo`, not `--store=demo`). Additional
+Shopify flags go after `--`. Put targeting flags and `--dry-run` before `--`.
+The original `sd -- --port 9293` and `sl -- --json` forms remain supported;
+`--port` and `--json` also work directly. Nodelete/editor-sync defaults are
+configured in the dotfile.
+
+`--dry-run` prints the command without starting Shopify and redacts password
+values. Arguments are forwarded as an array, without `eval` or shell expansion.
+Normal commands inherit Shopify's interactive terminal and exit code.
+Shopify's live-theme protections remain in place.
+
+## Shell setup
+
+### macOS / Bash / Zsh
+
+No shell setup is needed for the installed executable commands. If you still load
+old aliases/functions from `base_custom_cli.sh`, they take precedence over
+executables. Remove the old Shopify definitions, or load the compatibility
+functions after the old file using `eval "$(sshop shell)"` in your shell profile.
+Restart the shell. General helpers in the original file are unaffected.
+
+### Windows Command Prompt and PowerShell
+
+Install with `npm.cmd install -g simplified-shopify-cli`. Command Prompt can use `sd`, `sp`, etc.
+In PowerShell, use `sd.cmd`, `sp.cmd`, `sl.cmd`, etc. to avoid conflicts with
+built-in aliases and npm PowerShell script execution policy restrictions:
+
+```powershell
+sinit.cmd --global
+sstores.cmd add demo example-store --global
+sd.cmd demo "My Theme" --dry-run
+```
+
+For exactly `sd`, `sp`, `sl`, etc. in PowerShell, add this one-time setup to your
+PowerShell profile (provided profile scripts are permitted in your environment):
+
+```powershell
+. ([scriptblock]::Create((sshop.cmd shell powershell | Out-String)))
+```
+
+It replaces matching PowerShell aliases with functions forwarding to the installed
+`.cmd` commands. This includes `sp`, `sl`, and `si`; their normal PowerShell
+meanings will change in that session. Remove the profile line and restart to
+restore the original behavior. No execution-policy changes are made by this package.
+
+Personal config on Windows is `%USERPROFILE%\.sshop.json`. Shopify CLI must be
+installed globally with npm. In WSL, install Node and both CLIs inside WSL and
+follow the Bash instructions.
+
+**Verification:** the [initial CI run](https://github.com/deanschulz4/Shopify-CLI-Simplified/actions/runs/34994515508)
+passed the Node 22/24 matrix on macOS, Linux, and Windows, including installed
+commands, real Shopify CLI help invocation, and Windows PowerShell shortcuts.
+Each subsequent change must pass its own CI run. Live Shopify login/pull/dev
+workflows remain a separate pre-release check.
+
+## Migrate the original file
+
+```sh
+sshop import ./base_custom_cli.sh --global
+```
+
+Import reads literal entries from `map_store()` without sourcing the shell file.
+Identical duplicate mappings are collapsed; conflicting duplicates or existing
+aliases with different destinations stop the import. Other shell logic is ignored.
+Use a local import first if you want to inspect the result before changing your
+personal config.
+
+The original file stays unchanged as a local reference. General terminal,
+Node/nvm, BigCommerce, and NopCommerce helpers remain there; this first package
+focuses on Shopify. The old `sync` helper remains there too: its hard-coded
+`origin/master` merge and checkout behavior needs a separate configurable design.
+It is not installed by this package. The old `fix` permissions alias and `gitfix`
+are also not exported. `clis` is still the ordinary Shopify installation command.
+
+## Development and verification
+
+```sh
+npm run release:check
+npm pack
+```
+
+Tests cover config resolution, migration, argument handling, shell forwarding,
+and subprocess exit codes using a fake Shopify executable. They do not contact
+stores. The CI workflow checks Node 22/24 on macOS, Linux, and Windows and runs
+`npm run release:check` to inspect and install the actual npm archive.
+Native Windows dispatch supports the global npm installation of Shopify CLI.
+
+Shopify command behavior follows the official [theme pull](https://shopify.dev/docs/api/shopify-cli/theme/theme-pull)
+and [theme dev](https://shopify.dev/docs/api/shopify-cli/theme/theme-dev) documentation.
+
+## Uninstall
+
+```sh
+npm uninstall -g simplified-shopify-cli
+```
+
+Remove the optional shell startup line and restart your shell. Config files stay
+in place for reuse; remove them yourself when no longer needed.
+
+## License
+
+[MIT](LICENSE). The copyright attribution is public; personal store configuration is excluded from the npm package.

package/bin/lo.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('logout');

package/bin/sc.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('check');

package/bin/sconfig.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('config');

package/bin/sd.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('dev');

package/bin/sf.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('fix');

package/bin/shelp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('help');

package/bin/si.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('info');

package/bin/simport.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('import');

package/bin/sinit.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('init');

package/bin/sl.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('list');

package/bin/sp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('pull');

package/bin/spa.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('pull-all');

package/bin/spl.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('pull-json');

package/bin/sshop.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  console.error(`sshop: ${error.message}`);
+  process.exitCode = 1;
+}

package/bin/sstores.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runEntry } from '../src/entry.js';
+await runEntry('stores');

package/docs/RELEASING.md

@@ -0,0 +1,38 @@
+# Release 0.1.0
+
+Initial release: configurable store aliases, personal/project JSON configuration,
+direct commands, optional Bash/Zsh and PowerShell integration, literal legacy
+alias import, dry-run output, development port shorthand (`sd -p`), JSON output
+(`sl -j`, `si -j`), global configuration (`-g`), and development selection (`-d`).
+
+## Verification
+
+- Node 22/24 CI on macOS, Linux, and Windows checks the installed archive,
+  command entry points, real Shopify CLI help, and PowerShell shortcuts.
+- `npm run release:check` checks syntax, runs tests, builds and installs an
+  isolated archive, and scans for known credential formats and private domains.
+- Live Shopify login, pull, development sync, and Ctrl+C against a disposable
+  store/theme have not been verified as part of this release. Automated tests
+  exercise argument forwarding without modifying stores.
+
+Personal `.sshop.json` and legacy `base_custom_cli.sh` are ignored and excluded
+from npm. The LICENSE contains the owner's public copyright attribution.
+Pattern checks reduce leakage risk; they are not a complete security audit.
+
+## Publishing procedure
+
+1. Update the version and documentation; run `npm run release:check`.
+2. Commit and require the current commit's CI run to pass.
+3. Build an archive with `npm pack`, inspect `npm publish ARCHIVE --dry-run`,
+   then publish that archive with `npm publish ARCHIVE --access public`.
+4. Verify registry integrity, install the exact released version, and tag its
+   source commit. npm versions are immutable; corrections need a new version.
+
+## Install
+
+```sh
+npm install -g simplified-shopify-cli
+```
+
+Use `sd`, `sp`, `sl`, and the other commands directly. A CDN is not required
+for this Node-based CLI. Authentication remains managed by Shopify CLI.

package/examples/sshop.example.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "stores": {
+    "demo": "example-store.myshopify.com",
+    "sandbox": "example-sandbox.myshopify.com"
+  },
+  "defaultStore": "sandbox",
+  "defaults": {
+    "nodelete": true,
+    "themeEditorSync": true
+  }
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "simplified-shopify-cli",
+  "version": "0.1.0",
+  "description": "Configurable store aliases and shortcuts for Shopify theme development",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "sshop": "bin/sshop.js",
+    "sd": "bin/sd.js",
+    "sp": "bin/sp.js",
+    "sl": "bin/sl.js",
+    "si": "bin/si.js",
+    "spl": "bin/spl.js",
+    "spa": "bin/spa.js",
+    "sc": "bin/sc.js",
+    "sf": "bin/sf.js",
+    "lo": "bin/lo.js",
+    "sstores": "bin/sstores.js",
+    "sconfig": "bin/sconfig.js",
+    "sinit": "bin/sinit.js",
+    "simport": "bin/simport.js",
+    "shelp": "bin/shelp.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "shell/",
+    "examples/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check bin/sshop.js && node --check src/cli.js && node --check src/config.js && node --check src/commands.js",
+    "prepack": "npm run check && npm test",
+    "release:check": "npm run check && npm test && node scripts/check-package.js"
+  },
+  "keywords": [
+    "shopify",
+    "cli",
+    "themes",
+    "aliases"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deanschulz4/Shopify-CLI-Simplified.git"
+  },
+  "homepage": "https://github.com/deanschulz4/Shopify-CLI-Simplified#readme",
+  "bugs": {
+    "url": "https://github.com/deanschulz4/Shopify-CLI-Simplified/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/shell/shortcuts.ps1

@@ -0,0 +1,15 @@
+# Optional: dot-source from your PowerShell profile to use bare names such as sp.
+# PowerShell has built-in aliases for some of these names. Replace those aliases
+# in the current session only; removing the profile line and restarting restores them.
+foreach ($shortcutName in @('sl', 'si', 'sp', 'sd', 'spl', 'spa', 'sc', 'sf', 'lo')) {
+    Remove-Item "Alias:$shortcutName" -Force -ErrorAction SilentlyContinue
+}
+function global:sl { & sl.cmd @args }
+function global:si { & si.cmd @args }
+function global:sp { & sp.cmd @args }
+function global:sd { & sd.cmd @args }
+function global:spl { & spl.cmd @args }
+function global:spa { & spa.cmd @args }
+function global:sc { & sc.cmd @args }
+function global:sf { & sf.cmd @args }
+function global:lo { & lo.cmd @args }

package/shell/shortcuts.sh

@@ -0,0 +1,12 @@
+# Optional Bash/Zsh shortcuts. Source after your previous aliases to replace these names.
+# Remove this source line to uninstall shortcuts. Requires the installed commands on PATH.
+unalias sl si sp sd spl spa sc sf lo 2>/dev/null || :
+function sl { command sl "$@"; }
+function si { command si "$@"; }
+function sp { command sp "$@"; }
+function sd { command sd "$@"; }
+function spl { command spl "$@"; }
+function spa { command spa "$@"; }
+function sc { command sc "$@"; }
+function sf { command sf "$@"; }
+function lo { command lo "$@"; }

package/src/cli.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { filename, loadConfig, readConfig, writeConfig, normalizeStore, validateAlias, importAliases } from './config.js';
+import { buildCommand, formatCommand } from './commands.js';
+
+const help = `Simplified Shopify CLI (sshop)
+
+Usage: sshop [--config FILE] COMMAND [arguments]
+
+  init [--global]                    Create an empty config (never overwrites)
+  stores                            List merged store aliases
+  stores add ALIAS STORE [--global]  Add/update a store in the selected config
+  stores remove ALIAS [--global]     Remove a store from the selected config
+  import FILE [--global]             Import literal map_store aliases
+  config                            Show effective config and source files
+  shell [powershell]                Print shell functions (optional)
+
+  list|sl [store]                    List all themes
+  info|si [store]                    Show theme environment
+  dev|sd [store] [theme]             Develop with Theme Editor sync
+  pull|sp [store] [theme] [-p]       Pull theme, preserving unmatched local files
+  pull-json|spl [store] [theme]      Pull templates/config JSON only
+  pull-all|spa [store] [theme]       Pull without --nodelete
+  check|sc                          Run Theme Check
+  fix|sf                            Auto-correct Theme Check findings
+  logout|lo                         Log out of Shopify
+
+Options: --store/-s STORE, --theme/-t THEME, --dry-run
+Dev options: --port/-p PORT (example: sd demo -p 9293)
+List/info options: --json/-j (example: sl demo -j)
+Pull options: --live, --development/-d, --json-only/-p
+Info options: --development/-d
+Config writes: --global/-g (init, stores add/remove, import)
+Additional Shopify flags go after -- (example: -- --port 9293).
+Select the current store with si STORE; then omit STORE on later theme commands.
+A configured defaultStore overrides the remembered Shopify store. Use si to check.
+Use explicit --store for an unmapped store prefix with no theme.
+Pull defaults to the live theme. Dev without a theme uses a development theme.
+Config order: ~/.sshop.json, nearest .sshop.json; --config or SSHOP_CONFIG isolates.
+Direct commands: sd, sp, sl, si, spl, spa, sc, sf, lo.
+Setup commands: sinit, sstores, sconfig, simport, shelp.
+`;
+
+export async function main(argv) {
+  const args = [...argv];
+  let explicit = process.env.SSHOP_CONFIG;
+  if (args[0] === '--config') {
+    explicit = args[1];
+    if (!explicit || explicit.startsWith('-')) throw new Error('Provide a file after --config.');
+    args.splice(0, 2);
+  }
+  const command = args.shift();
+  if (!command || ['--help', '-h', 'help'].includes(command)) { console.log(help); return 0; }
+  if (command === '--version') {
+    console.log(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version); return 0;
+  }
+  if (command === 'shell') {
+    if (args.length > 1 || (args.length === 1 && args[0] !== 'powershell')) throw new Error('Usage: sshop shell [powershell]');
+    console.log(fs.readFileSync(new URL(args[0] === 'powershell' ? '../shell/shortcuts.ps1' : '../shell/shortcuts.sh', import.meta.url), 'utf8')); return 0;
+  }
+  const mutation = command === 'init' || command === 'import' || (command === 'stores' && ['add', 'remove'].includes(args[0]));
+  if (mutation) {
+    const normalized = args.map(arg => arg === '-g' ? '--global' : arg);
+    const global = normalized.includes('--global');
+    if (global && explicit) throw new Error('Choose --global or --config, not both.');
+    if (normalized.filter(arg => arg === '--global').length > 1) throw new Error('Repeated --global option.');
+    const values = normalized.filter(arg => arg !== '--global');
+    const file = explicit ? path.resolve(explicit) : path.join(global ? os.homedir() : process.cwd(), filename);
+    if (command === 'init') {
+      if (values.length) throw new Error('Usage: sshop init [--global]');
+      writeConfig(file, { version: 1, stores: {}, defaults: { nodelete: true, themeEditorSync: true } }, { create: true });
+    } else {
+      const config = fs.existsSync(file) ? readConfig(file) : { version: 1, stores: {} };
+      if (command === 'import') {
+        if (values.length !== 1) throw new Error('Usage: sshop import FILE [--global]');
+        const stores = importAliases(fs.readFileSync(values[0], 'utf8'));
+        for (const [alias, store] of Object.entries(stores)) {
+          if (Object.hasOwn(config.stores, alias) && normalizeStore(config.stores[alias]) !== store) throw new Error(`Import would overwrite alias ${alias}. Remove or update it explicitly first.`);
+        }
+        config.stores = { ...config.stores, ...stores };
+        console.log(`Imported ${Object.keys(stores).length} unique store aliases.`);
+      } else if (values[0] === 'add') {
+        if (values.length !== 3) throw new Error('Usage: sshop stores add ALIAS STORE [--global]');
+        validateAlias(values[1]); config.stores[values[1]] = normalizeStore(values[2]);
+      } else {
+        if (values.length !== 2) throw new Error('Usage: sshop stores remove ALIAS [--global]');
+        if (!Object.hasOwn(config.stores, values[1])) throw new Error(`Alias ${values[1]} does not exist in ${file}.`);
+        delete config.stores[values[1]];
+        if (config.defaultStore === values[1]) config.defaultStore = null;
+      }
+      writeConfig(file, config, { create: !fs.existsSync(file) });
+    }
+    console.log(`Saved ${file}`); return 0;
+  }
+  const loaded = loadConfig({ explicit });
+  if (command === 'config') {
+    if (args.length) throw new Error('Usage: sshop config');
+    console.log(JSON.stringify(loaded, null, 2)); return 0;
+  }
+  if (command === 'stores') {
+    if (args.length && !(args.length === 1 && args[0] === 'list')) throw new Error('Usage: sshop stores [list|add|remove]');
+    const entries = Object.entries(loaded.config.stores).sort(([a], [b]) => a.localeCompare(b));
+    console.log(entries.length ? entries.map(([alias, store]) => `${alias}\t${normalizeStore(store)}`).join('\n') : 'No store aliases yet. Run: sshop stores add demo example-store');
+    return 0;
+  }
+  const built = buildCommand(command, args, loaded.config);
+  if (built.dryRun) { console.log(formatCommand(built.args)); return 0; }
+  return runShopify(built.args);
+}
+
+export async function runShopify(args, { platform = process.platform } = {}) {
+  // Use argument arrays, never eval or a shell command string.
+  // Windows npm exposes shopify.cmd; invoke the package's JS entry with Node instead.
+  let executable = 'shopify';
+  if (platform === 'win32') {
+    const directories = (process.env.PATH || '').split(path.delimiter);
+    let entry;
+    for (const directory of directories) {
+      const root = path.join(directory, 'node_modules', '@shopify', 'cli');
+      const manifest = path.join(root, 'package.json');
+      if (!fs.existsSync(manifest)) continue;
+      const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.shopify;
+      if (bin && fs.existsSync(path.join(root, bin))) { entry = path.join(root, bin); break; }
+    }
+    if (!entry) throw new Error('Shopify CLI not found. Install it globally with npm install -g @shopify/cli.');
+    executable = process.execPath;
+    args = [entry, ...args];
+  }
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { stdio: 'inherit', shell: false });
+    const forwardInterrupt = () => { if (!child.killed) child.kill('SIGINT'); };
+    const forwardTerminate = () => { if (!child.killed) child.kill('SIGTERM'); };
+    process.on('SIGINT', forwardInterrupt);
+    process.on('SIGTERM', forwardTerminate);
+    const cleanup = () => { process.off('SIGINT', forwardInterrupt); process.off('SIGTERM', forwardTerminate); };
+    child.once('error', error => {
+      cleanup(); reject(new Error(error.code === 'ENOENT' ? 'Shopify CLI not found. Install it with npm install -g @shopify/cli.' : error.message));
+    });
+    child.once('exit', (code, signal) => { cleanup(); resolve(code ?? (signal === 'SIGINT' ? 130 : 143)); });
+  });
+}

package/src/commands.js

@@ -0,0 +1,101 @@
+import { normalizeStore } from './config.js';
+
+const names = { sl: 'list', si: 'info', sp: 'pull', sd: 'dev', spl: 'pull-json', spa: 'pull-all', sc: 'check', sf: 'fix', lo: 'logout' };
+export function buildCommand(name, input, config) {
+  const command = names[name] || name;
+  if (!['list', 'info', 'pull', 'dev', 'pull-json', 'pull-all', 'check', 'fix', 'logout'].includes(command)) throw new Error(`Unknown command: ${name}. Run sshop --help.`);
+  const separator = input.indexOf('--');
+  const args = separator < 0 ? input : input.slice(0, separator);
+  const extra = separator < 0 ? [] : input.slice(separator + 1);
+  const positionals = [];
+  let store, theme, selector, json = command === 'pull-json';
+  let dryRun = false, port, jsonOutput = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--dry-run') { dryRun = true; continue; }
+    if (arg === '-j' || arg === '--json') {
+      if (!['list', 'info'].includes(command)) throw new Error('--json/-j applies only to list and info. For JSON-only pulls, use -p.');
+      if (jsonOutput) throw new Error('JSON output specified more than once.');
+      jsonOutput = true;
+      continue;
+    }
+    if (arg === '--port' || (arg === '-p' && command === 'dev')) {
+      if (command !== 'dev') throw new Error('--port applies only to dev.');
+      if (port !== undefined) throw new Error('Port specified more than once.');
+      port = args[++i];
+      if (!port || !/^\d+$/.test(port) || Number(port) < 1 || Number(port) > 65535) throw new Error('Port must be a number from 1 to 65535. Example: sd demo -p 9293');
+      continue;
+    }
+    if (arg === '-p' || arg === '--json-only') { json = true; continue; }
+    if (arg === '--live' || arg === '--development' || arg === '-d') {
+      if (selector) throw new Error('Choose only one of --live or --development.');
+      selector = arg === '-d' ? '--development' : arg; continue;
+    }
+    if (['--store', '-s', '--theme', '-t'].includes(arg)) {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) throw new Error(`Missing value for ${arg}.`);
+      if (arg === '--store' || arg === '-s') {
+        if (store !== undefined) throw new Error('Store specified more than once.');
+        store = value;
+      } else {
+        if (theme !== undefined) throw new Error('Theme specified more than once.');
+        theme = value;
+      }
+      continue;
+    }
+    if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}. Put additional Shopify flags after --.`);
+    positionals.push(arg);
+  }
+  const pull = ['pull', 'pull-json', 'pull-all'].includes(command);
+  const thematic = pull || command === 'dev';
+  if (command === 'list' || command === 'info') {
+    if (positionals.length > 1 || (store && positionals.length)) throw new Error('Provide a single store.');
+    store ??= positionals.shift();
+  } else if (thematic) {
+    if (!store && positionals.length && (positionals.length > 1 || Object.hasOwn(config.stores, positionals[0]) || /[./]/.test(positionals[0]))) store = positionals.shift();
+    if (positionals.length > 1 || (theme && positionals.length)) throw new Error('Use [store] [theme], or explicit --store and --theme.');
+    theme ??= positionals.shift();
+  } else if (positionals.length || store || theme || selector || json) {
+    throw new Error(`${command} does not accept store, theme, or pull options.`);
+  }
+  if (json && !pull) throw new Error('--json-only applies only to pull.');
+  if (selector && !pull && !(command === 'info' && selector === '--development')) throw new Error('--live applies only to pull; --development/-d applies to pull and info.');
+  if (theme && selector) throw new Error('Use either --theme or a theme selector, not both.');
+  if (theme && !thematic && command !== 'info') throw new Error(`${command} does not accept a theme.`);
+  store ??= config.defaultStore;
+  const output = command === 'logout' ? ['auth', 'logout'] : ['theme', command === 'fix' ? 'check' : pull ? 'pull' : command];
+  if (store && (thematic || ['list', 'info'].includes(command))) output.push('--store', normalizeStore(Object.hasOwn(config.stores, store) ? config.stores[store] : store));
+  if (theme) output.push('--theme', theme);
+  if (pull) {
+    if (!theme) output.push(selector || '--live');
+    if (command !== 'pull-all' && config.defaults.nodelete !== false) output.push('--nodelete');
+    if (json) output.push('--only', 'templates/*.json', '--only', 'config/*.json');
+  }
+  if (command === 'info' && selector) output.push(selector);
+  if (command === 'dev' && config.defaults.themeEditorSync !== false) output.push('--theme-editor-sync');
+  if (port !== undefined) {
+    if (extra.some(arg => arg === '--port' || arg.startsWith('--port='))) throw new Error('Port specified more than once.');
+    output.push('--port', port);
+  }
+  if (command === 'fix') output.push('--auto-correct');
+  if (jsonOutput) {
+    if (extra.some(arg => arg === '-j' || arg === '--json' || arg.startsWith('--json='))) throw new Error('JSON output specified more than once.');
+    output.push('--json');
+  }
+  // Prevent ambiguous duplicate targeting and accidental reinterpretation of wrapper defaults.
+  const reserved = /^(?:--(?:store|theme|live|development|nodelete|theme-editor-sync)|-[stldn])(?:=|$)/;
+  if (extra.some(arg => reserved.test(arg) || /^-[st].+/.test(arg))) throw new Error('Pass store/theme/selector options before --; set nodelete and themeEditorSync in config.');
+  return { args: [...output, ...extra], dryRun };
+}
+
+export function formatCommand(args) {
+  const redacted = [];
+  let secret = false;
+  for (const arg of args) {
+    if (secret) { redacted.push('[redacted]'); secret = false; continue; }
+    if (/^--(?:password|store-password)=/.test(arg)) { redacted.push(`${arg.split('=')[0]}=[redacted]`); continue; }
+    redacted.push(arg);
+    secret = ['--password', '--store-password'].includes(arg);
+  }
+  return ['shopify', ...redacted].map(arg => /^[a-zA-Z0-9_./:-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(' ');
+}

package/src/config.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const filename = '.sshop.json';
+const own = (object, key) => Object.hasOwn(object, key);
+export function normalizeStore(value) {
+  if (typeof value !== 'string') throw new Error('Store must be a string.');
+  const slug = value.trim().toLowerCase().replace(/^https?:\/\//, '').replace(/\/$/, '').replace(/\.myshopify\.com$/, '');
+  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(slug) || slug.length > 63) {
+    throw new Error(`Invalid Shopify store: ${value}. Use a store prefix or a myshopify.com domain.`);
+  }
+  return `${slug}.myshopify.com`;
+}
+export function validateAlias(alias) {
+  if (!/^[a-z][a-z0-9_-]*$/.test(alias) || ['__proto__', 'prototype', 'constructor'].includes(alias)) {
+    throw new Error('Alias must start with a lowercase letter and contain only lowercase letters, digits, _ or -.');
+  }
+}
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('Config must be a JSON object.');
+  for (const key of Object.keys(config)) {
+    if (!['version', 'stores', 'defaultStore', 'defaults'].includes(key)) throw new Error(`Unknown config key: ${key}`);
+  }
+  if (config.version !== 1) throw new Error('Config version must be 1.');
+  if (!config.stores || typeof config.stores !== 'object' || Array.isArray(config.stores)) throw new Error('Config stores must be an object.');
+  for (const [alias, store] of Object.entries(config.stores)) { validateAlias(alias); normalizeStore(store); }
+  if (config.defaultStore !== undefined && config.defaultStore !== null) {
+    if (typeof config.defaultStore !== 'string' || !config.defaultStore.trim()) throw new Error('defaultStore must be a store alias, domain, or null.');
+    if (!own(config.stores, config.defaultStore)) normalizeStore(config.defaultStore);
+  }
+  if (config.defaults !== undefined) {
+    if (!config.defaults || typeof config.defaults !== 'object' || Array.isArray(config.defaults)) throw new Error('defaults must be an object.');
+    for (const [key, value] of Object.entries(config.defaults)) {
+      if (!['nodelete', 'themeEditorSync'].includes(key) || typeof value !== 'boolean') throw new Error(`Invalid default: ${key}. Supported boolean defaults: nodelete, themeEditorSync.`);
+    }
+  }
+  return config;
+}
+export function readConfig(file) {
+  try { return validateConfig(JSON.parse(fs.readFileSync(file, 'utf8'))); }
+  catch (error) { throw new Error(`${file}: ${error.message}`); }
+}
+export function loadConfig({ cwd = process.cwd(), home = os.homedir(), explicit = process.env.SSHOP_CONFIG } = {}) {
+  const globalFile = path.join(home, filename);
+  let files = [];
+  if (explicit) {
+    files = [path.resolve(cwd, explicit)];
+  } else {
+    if (fs.existsSync(globalFile)) files.push(globalFile);
+    let directory = path.resolve(cwd);
+    while (true) {
+      const candidate = path.join(directory, filename);
+      if (fs.existsSync(candidate)) { if (!files.includes(candidate)) files.push(candidate); break; }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  }
+  let config = { version: 1, stores: {}, defaults: { nodelete: true, themeEditorSync: true } };
+  for (const file of files) {
+    const next = readConfig(file);
+    config = { ...config, ...next, stores: { ...config.stores, ...next.stores }, defaults: { ...config.defaults, ...next.defaults } };
+  }
+  return { config, files };
+}
+export function writeConfig(file, config, { create = false } = {}) {
+  validateConfig(config);
+  const data = `${JSON.stringify(config, null, 2)}\n`;
+  if (create) { fs.writeFileSync(file, data, { flag: 'wx', mode: 0o600 }); return; }
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try { fs.writeFileSync(temporary, data, { flag: 'wx', mode: 0o600 }); fs.renameSync(temporary, file); }
+  finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+}
+// Parse only literal map_store case entries. Never source or execute the legacy file.
+export function importAliases(source) {
+  const block = source.match(/map_store\(\)\s*\{([\s\S]*?)\n\}/)?.[1];
+  if (!block) throw new Error('No map_store() block found.');
+  const stores = {};
+  for (const match of block.matchAll(/^\s*([a-z][a-z0-9_-]*)\)\s*printf\s+'%s'\s+'([^']+)'\s*;;\s*$/gm)) {
+    const [, alias, store] = match;
+    validateAlias(alias);
+    const normalized = normalizeStore(store);
+    if (own(stores, alias) && stores[alias] !== normalized) throw new Error(`Conflicting legacy alias: ${alias}`);
+    stores[alias] = normalized;
+  }
+  if (!Object.keys(stores).length) throw new Error('No supported literal store mappings found.');
+  return stores;
+}

package/src/entry.js

@@ -0,0 +1,13 @@
+import { main } from './cli.js';
+
+export async function runEntry(command, input = process.argv.slice(2)) {
+  const args = [...input];
+  const global = [];
+  if (args[0] === '--config') global.push(...args.splice(0, 2));
+  try {
+    process.exitCode = await main([...global, ...(['--help', '-h', '--version'].includes(args[0]) ? args : [command, ...args])]);
+  } catch (error) {
+    console.error(`${command}: ${error.message}`);
+    process.exitCode = 1;
+  }
+}