@acidgreen-au/ag-cicd-cli 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,32 @@
+# @acidgreen-au/ag-cicd-cli
+
+CLI tools for Acidgreen CI/CD workflows. Provides commands for Shopify theme deployment, code quality checks, environment validation, and git automation.
+
+## Installation
+
+```bash
+pnpm install -g @acidgreen-au/ag-cicd-cli
+```
+
+Or use directly with npx:
+
+```bash
+pnpx @acidgreen-au/ag-cicd-cli <command>
+```
+
+## Usage
+
+```bash
+ag --help
+```
+
+For help with a specific command:
+
+```bash
+ag <command> --help
+```
+
+## Requirements
+
+- Node.js >= 24.0.0
+- Shopify CLI (for theme commands)

package/dist/cli.mjs

@@ -1,13 +1,60 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { program } from "commander";
-import { execSync, spawn } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import prompts from "prompts";
+import { parse, stringify } from "smol-toml";
+import concurrently from "concurrently";
 
 //#region src/commands/check-tag.ts
+const helpText$9 = `
+Details:
+  Reads the version from package.json and checks if a corresponding git tag
+  exists. Optionally creates and pushes the tag if it doesn't exist.
+
+  When --remote is specified, local tags are synced with remote before checking.
+
+  Used in CI/CD to automatically tag releases when package.json version
+  is bumped.
+
+Exit Codes:
+  0  Tag exists, or was successfully created
+  1  Tag does not exist (when --create is not specified)
+
+Examples:
+  $ ag check-tag
+  $ ag check-tag --create
+  $ ag check-tag --create --push
+  $ ag check-tag --create --push --remote origin
+  $ ag check-tag --prefix release-
+
+GitLab CI/CD Authentication:
+  To push tags from GitLab CI/CD, you need to authenticate with the remote.
+
+    Create a token with write_repository scope in Settings > Access Tokens,
+    then add it as a masked CI/CD variable (e.g., GITLAB_TOKEN).
+
+    $ ag check-tag --create --push \\
+        --remote "https://oauth2:\${GITLAB_TOKEN}@\${CI_SERVER_HOST}/\${CI_PROJECT_PATH}.git"`;
+function register$9(program$1) {
+	program$1.command("check-tag").description("Check if git tag exists for package.json version").addHelpText("after", helpText$9).option("-p, --package-path <path>", "Path to package.json", "package.json").option("--prefix <prefix>", "Tag prefix", "v").option("-c, --create", "Create the tag if it doesn't exist").option("--push", "Push the tag to remote (requires --create)").option("-r, --remote <remote>", "Remote to push to", "origin").action(checkTagCommand);
+}
 function getVersionFromPackage(packagePath) {
 	const content = readFileSync(packagePath, "utf-8");
 	return JSON.parse(content).version;
 }
+function syncTagsFromRemote(remote) {
+	execSync(`git fetch "${remote}" --prune --prune-tags --force`, {
+		encoding: "utf-8",
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+}
 function tagExists(tag) {
 	try {
 		execSync(`git rev-parse --verify "refs/tags/${tag}"`, {
@@ -47,6 +94,7 @@ function checkTag(options) {
 	const packagePath = options.packagePath ?? "package.json";
 	const prefix = options.prefix ?? "v";
 	const remote = options.remote ?? "origin";
+	if (options.remote) syncTagsFromRemote(remote);
 	const version = getVersionFromPackage(packagePath);
 	const tag = `${prefix}${version}`;
 	if (tagExists(tag)) return {
@@ -245,6 +293,24 @@ const ALL_CHECKS = [
 	"theme-check",
 	"tsc"
 ];
+const helpText$8 = `
+Checks:
+  biome        Runs Biome linter for TypeScript/JavaScript
+  prettier     Checks file formatting with Prettier
+  theme-check  Runs Shopify Theme Check for Liquid files
+  tsc          Runs TypeScript compiler for type errors
+
+Output:
+  Generates a JSON file compatible with GitLab Code Quality reports.
+  Each issue includes severity, file path, and line number.
+
+Examples:
+  $ ag codequality
+  $ ag codequality --checks biome tsc
+  $ ag codequality --output gl-code-quality.json --path ./theme`;
+function register$8(program$1) {
+	program$1.command("codequality").description("Run code quality checks and output GitLab-compatible JSON").addHelpText("after", helpText$8).option("-o, --output <file>", "Output JSON file path", "codequality.json").option("-p, --path <path>", "Theme directory path", "theme").option("-c, --checks <checks...>", "Specific checks to run (biome, prettier, theme-check, tsc)").action(codequality);
+}
 function codequality(options) {
 	const { output, path, checks = ALL_CHECKS } = options;
 	const allIssues = [];
@@ -280,6 +346,28 @@ function codequality(options) {
 
 //#endregion
 //#region src/commands/commit-msg.ts
+const helpText$7 = `
+Details:
+  Validates that commit messages follow the required format:
+    <PREFIX>-<NUMBER> <message>
+
+  When the branch contains a ticket ID, the commit message must reference
+  the same ticket. Branches without ticket IDs (main, development, etc.) skip
+  this check.
+
+  Designed to be called from .husky/commit-msg hook:
+    ag commit-msg --file "$1"
+
+Exit Codes:
+  0  Commit message is valid
+  1  Commit message is invalid (blocks commit)
+
+Examples:
+  $ ag commit-msg --file .git/COMMIT_EDITMSG
+  $ ag commit-msg -f .git/COMMIT_EDITMSG --prefix PROJ`;
+function register$7(program$1) {
+	program$1.command("commit-msg").description("Validate commit message format for git hooks").addHelpText("after", helpText$7).requiredOption("-f, --file <file>", "Path to commit message file").option("-p, --prefix <prefix>", "JIRA project prefix", "AIR").action(commitMsg);
+}
 function validateCommitMsg(options) {
 	const { file, prefix } = options;
 	const ticketRegex = /* @__PURE__ */ new RegExp(`^${prefix}-[0-9]+`);
@@ -337,6 +425,82 @@ function commitMsg(options) {
 	process.exit(0);
 }
 
+//#endregion
+//#region src/commands/config-shopify.ts
+const helpText$6 = `
+Details:
+  Creates or updates a shopify.theme.toml configuration file.
+
+  Without a name argument: Creates the default environment configuration.
+  With a name argument: Adds a new named environment, copying path and
+  ignore settings from the default environment.
+
+  Prompts for:
+    - Store name (required): Your myshopify.com store URL
+    - Theme ID (optional): Target theme ID for deployment
+
+Examples:
+  $ ag config:shopify                    # Create/update default environment
+  $ ag config:shopify production         # Add production environment
+  $ ag config:shopify staging --force    # Overwrite staging environment`;
+const DEFAULT_IGNORES = [
+	"templates/*.json",
+	"locales/*.json",
+	"config/settings_data.json",
+	"src/*",
+	"public/*"
+];
+const DEFAULT_PATH = "theme";
+function register$6(program$1) {
+	program$1.command("config:shopify").description("Create or update shopify.theme.toml configuration").addHelpText("after", helpText$6).argument("[name]", "Environment name (default: 'default')").option("-f, --force", "Overwrite existing environment").action(configShopify);
+}
+function loadConfig(configPath) {
+	if (!existsSync(configPath)) return { environments: {} };
+	return parse(readFileSync(configPath, "utf-8"));
+}
+function saveConfig(configPath, config) {
+	writeFileSync(configPath, stringify(config));
+}
+async function configShopify(name, options) {
+	const configPath = "shopify.theme.toml";
+	const envName = name ?? "default";
+	const config = loadConfig(configPath);
+	if (!config.environments) config.environments = {};
+	if (config.environments[envName] && !options.force) {
+		console.error(`Error: Environment '${envName}' already exists. Use --force to overwrite.`);
+		process.exit(1);
+	}
+	if (envName !== "default" && !config.environments.default) {
+		console.error("Error: Default environment must be created first. Run 'ag config:shopify' without arguments.");
+		process.exit(1);
+	}
+	const response = await prompts([{
+		type: "text",
+		name: "store",
+		message: "Store name (e.g., my-store.myshopify.com)",
+		validate: (value) => value.length > 0 || "Store name is required"
+	}, {
+		type: "text",
+		name: "themeId",
+		message: "Theme ID (optional, press Enter to skip)"
+	}], { onCancel: () => {
+		console.log("\nCancelled.");
+		process.exit(0);
+	} });
+	const defaultEnv = config.environments.default;
+	const path = defaultEnv?.path ?? DEFAULT_PATH;
+	const ignore = defaultEnv?.ignore ?? DEFAULT_IGNORES;
+	const envConfig = {
+		store: response.store,
+		path,
+		ignore
+	};
+	if (response.themeId) envConfig.theme = response.themeId;
+	config.environments[envName] = envConfig;
+	saveConfig(configPath, config);
+	console.log(`\n${existsSync(configPath) ? "Updated" : "Created"} ${configPath} with '${envName}' environment`);
+}
+
 //#endregion
 //#region src/utils/shopify.ts
 function listThemes() {
@@ -375,6 +539,26 @@ const defaultIgnores = [
 
 //#endregion
 //#region src/commands/deploy.ts
+const helpText$5 = `
+Details:
+  Pushes theme files to a specific Shopify theme ID. Use this for deploying
+  to staging or production themes where you know the target theme ID.
+
+  Writes deployment info to deploy.env:
+    - PREVIEW_URL: Theme preview URL
+    - EDITOR_URL: Theme editor URL
+    - THEME_ID: Deployed theme ID
+
+Environment:
+  SHOPIFY_CLI_THEME_TOKEN  Shopify CLI authentication token
+  SHOPIFY_FLAG_STORE       Shopify store URL
+
+Examples:
+  $ ag deploy --theme-id 123456789
+  $ ag deploy -t 123456789 --path ./theme`;
+function register$5(program$1) {
+	program$1.command("deploy").description("Deploy theme to an existing Shopify theme by ID").addHelpText("after", helpText$5).requiredOption("-t, --theme-id <id>", "Target Shopify theme ID").option("-p, --path <path>", "Theme directory path", "theme").action(deploy);
+}
 function deploy(options) {
 	const { themeId, path } = options;
 	const themeIdNum = parseInt(themeId, 10);
@@ -387,6 +571,31 @@ function deploy(options) {
 
 //#endregion
 //#region src/commands/deploy-review.ts
+const helpText$4 = `
+Details:
+  Creates or updates an unpublished theme for reviewing branch changes.
+  Theme is named "AG Preview: <branch>" for easy identification.
+
+  On first deploy: Clones the live theme as a starting point.
+  On subsequent deploys: Updates the existing preview theme.
+
+  Writes deployment info to deploy.env:
+    - PREVIEW_URL: Theme preview URL
+    - EDITOR_URL: Theme editor URL
+    - THEME_ID: Preview theme ID
+    - EXISTING_THEME_ID: ID if theme already existed
+
+Environment:
+  SHOPIFY_CLI_THEME_TOKEN  Shopify CLI authentication token
+  SHOPIFY_FLAG_STORE       Shopify store URL
+  CI_COMMIT_REF_NAME       Git branch name (GitLab CI)
+
+Examples:
+  $ ag deploy:review --branch feature/new-header
+  $ ag deploy:review -b $CI_COMMIT_REF_NAME`;
+function register$4(program$1) {
+	program$1.command("deploy:review").description("Deploy a review app theme for the current branch").addHelpText("after", helpText$4).requiredOption("-b, --branch <branch>", "Git branch name").option("-p, --path <path>", "Theme directory path", "theme").action(deployReview);
+}
 function deployReview(options) {
 	const { branch, path } = options;
 	const themeName = `AG Preview: ${branch}`;
@@ -413,48 +622,71 @@ function deployReview(options) {
 
 //#endregion
 //#region src/commands/dev.ts
-function dev(_options, command) {
-	const themeArgs = command.args;
-	console.log("Starting development servers...");
-	const vite = spawn("pnpm", ["exec", "vite"], {
-		stdio: "inherit",
-		shell: true
-	});
-	const shopify = spawn("pnpm", [
-		"exec",
-		"shopify",
-		"theme",
-		"dev",
-		...themeArgs
-	], {
-		stdio: "inherit",
-		shell: true
-	});
-	const cleanup = () => {
-		vite.kill();
-		shopify.kill();
-		process.exit(0);
-	};
-	process.on("SIGINT", cleanup);
-	process.on("SIGTERM", cleanup);
-	vite.on("close", (code) => {
-		if (code !== 0) {
-			console.error(`Vite exited with code ${code}`);
-			shopify.kill();
-			process.exit(code ?? 1);
-		}
-	});
-	shopify.on("close", (code) => {
-		if (code !== 0) {
-			console.error(`Shopify theme dev exited with code ${code}`);
-			vite.kill();
-			process.exit(code ?? 1);
-		}
+const helpText$3 = `
+Details:
+  Starts both Vite (for frontend asset compilation) and Shopify theme dev
+  servers in parallel. All additional arguments are passed to shopify theme dev.
+
+  Handles graceful shutdown of both processes on Ctrl+C or if either exits.
+
+Arguments:
+  Any arguments after -- are passed directly to 'shopify theme dev'.
+  Common options include --store, --theme, --live-reload, etc.
+  Run \`shopify theme dev -h\` for full list of options.
+
+Examples:
+  $ ag dev
+  $ ag dev -- --store my-store
+  $ ag dev -- --theme 123456789`;
+function register$3(program$1) {
+	program$1.command("dev").description("Start Vite and Shopify theme dev servers concurrently").addHelpText("after", helpText$3).allowUnknownOption().allowExcessArguments().action(dev);
+}
+async function dev(_options, command) {
+	const { result } = concurrently([{
+		command: "pnpm exec vite",
+		name: "vite",
+		prefixColor: "cyan"
+	}, {
+		command: `shopify theme dev ${command.args.join(" ")}`,
+		name: "shopify",
+		prefixColor: "magenta"
+	}], {
+		killOthers: ["failure", "success"],
+		restartTries: 0
 	});
+	try {
+		await result;
+	} catch {
+		process.exit(1);
+	}
 }
 
 //#endregion
 //#region src/commands/release.ts
+const helpText$2 = `
+Details:
+  Creates a new theme for production releases. Clones the current live theme
+  to preserve any theme editor customizations, then pushes your code changes.
+
+  Theme is named "AG Release: <name>" for easy identification.
+
+  Writes deployment info to deploy.env:
+    - PREVIEW_URL: Release theme preview URL
+    - EDITOR_URL: Release theme editor URL
+    - THEME_ID: New release theme ID
+    - PUBLISHED_THEME_ID: Current live theme ID (for rollback)
+
+Environment:
+  SHOPIFY_CLI_THEME_TOKEN  Shopify CLI authentication token
+  SHOPIFY_FLAG_STORE       Shopify store URL
+  CI_COMMIT_TAG            Git tag (GitLab CI)
+
+Examples:
+  $ ag release --name v1.2.3
+  $ ag release -n $CI_COMMIT_TAG`;
+function register$2(program$1) {
+	program$1.command("release").description("Create a release theme by cloning live and pushing changes").addHelpText("after", helpText$2).requiredOption("-n, --name <name>", "Release name (usually git tag)").option("-p, --path <path>", "Theme directory path", "theme").action(release);
+}
 function release(options) {
 	const { name, path } = options;
 	const themeName = `AG Release: ${name}`;
@@ -471,6 +703,24 @@ function release(options) {
 
 //#endregion
 //#region src/commands/stop-review.ts
+const helpText$1 = `
+Details:
+  Finds and deletes the unpublished theme named "AG Preview: <branch>".
+  Typically called when a merge request is closed or merged.
+
+  Safe to run even if the theme doesn't exist.
+
+Environment:
+  SHOPIFY_CLI_THEME_TOKEN  Shopify CLI authentication token
+  SHOPIFY_FLAG_STORE       Shopify store URL
+  CI_COMMIT_REF_NAME       Git branch name (GitLab CI)
+
+Examples:
+  $ ag stop:review --branch feature/new-header
+  $ ag stop:review -b $CI_COMMIT_REF_NAME`;
+function register$1(program$1) {
+	program$1.command("stop:review").description("Delete the review app theme for a branch").addHelpText("after", helpText$1).requiredOption("-b, --branch <branch>", "Git branch name").action(stopReview);
+}
 function stopReview(options) {
 	const { branch } = options;
 	const themeName = `AG Preview: ${branch}`;
@@ -485,6 +735,27 @@ function stopReview(options) {
 
 //#endregion
 //#region src/commands/validate-env.ts
+const helpText = `
+Contexts:
+  all          Check all variables for all contexts (default)
+  deploy       Check variables for theme deployment
+  review       Check variables for review app deployment
+  release      Check variables for release deployment
+  codequality  Check variables for code quality checks
+
+Details:
+  Validates that required environment variables are present before
+  running CI/CD jobs. Exits with code 1 if any required vars are missing.
+
+  Token values are redacted in output for security.
+
+Examples:
+  $ ag validate-env
+  $ ag validate-env --context deploy
+  $ ag validate-env --vars SHOPIFY_FLAG_STORE CUSTOM_VAR`;
+function register(program$1) {
+	program$1.command("validate-env").description("Validate required environment variables are set").addHelpText("after", helpText).option("-c, --context <context>", "Validation context (deploy, review, release, codequality, all)").option("-v, --vars <vars...>", "Specific variables to check").action(validateEnv);
+}
 const commonVars = [{
 	name: "SHOPIFY_CLI_THEME_TOKEN",
 	required: true,
@@ -568,16 +839,20 @@ function validateEnv(options) {
 
 //#endregion
 //#region src/cli.ts
-program.name("agci").description("Acidgreen CI/CD CLI tools").version("1.0.0");
-program.command("codequality").description("Run code quality checks and combine output").option("-o, --output <file>", "Output file", "codequality.json").option("-p, --path <path>", "Theme path", "theme").option("-c, --checks <checks...>", "Checks to run (biome, prettier, theme-check, tsc)").action(codequality);
-program.command("deploy:review").description("Deploy a review app for the current branch").requiredOption("-b, --branch <branch>", "Branch name (CI_COMMIT_REF_NAME)").option("-p, --path <path>", "Theme path", "theme").action(deployReview);
-program.command("stop:review").description("Stop and delete a review app").requiredOption("-b, --branch <branch>", "Branch name (CI_COMMIT_REF_NAME)").action(stopReview);
-program.command("deploy").description("Deploy to a specific theme").requiredOption("-t, --theme-id <id>", "Theme ID (SHOPIFY_THEME_ID)").option("-p, --path <path>", "Theme path", "theme").action(deploy);
-program.command("release").description("Create a release by cloning live theme and pushing").requiredOption("-n, --name <name>", "Release name/tag").option("-p, --path <path>", "Theme path", "theme").action(release);
-program.command("validate-env").description("Validate required environment variables are set").option("-c, --context <context>", "Context to validate (deploy, review, release, codequality, all)").option("-v, --vars <vars...>", "Specific environment variables to check").action(validateEnv);
-program.command("dev").description("Start Vite and Shopify theme dev servers concurrently").allowUnknownOption().allowExcessArguments().action(dev);
-program.command("commit-msg").description("Validate commit message format (for git hooks)").requiredOption("-f, --file <file>", "Path to commit message file").option("-p, --prefix <prefix>", "JIRA project prefix", "AIR").action(commitMsg);
-program.command("check-tag").description("Check if git tag exists for package.json version").option("-p, --package-path <path>", "Path to package.json", "package.json").option("--prefix <prefix>", "Tag prefix", "v").option("-c, --create", "Create the tag if it does not exist").option("--push", "Push the tag to remote (requires --create)").option("-r, --remote <remote>", "Remote to push to", "origin").action(checkTagCommand);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const binName = Object.keys(pkg.bin)[0];
+program.name(binName).description("Acidgreen CI/CD CLI tools for Shopify theme development").version(pkg.version);
+register$8(program);
+register$5(program);
+register$4(program);
+register$1(program);
+register$2(program);
+register(program);
+register$3(program);
+register$7(program);
+register$9(program);
+register$6(program);
 program.parse();
 
 //#endregion

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "@acidgreen-au/ag-cicd-cli",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Acidgreen CI/CD CLI tools",
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.com/acidgreen/internal/agcicd.git"
-  },
   "type": "module",
   "bin": {
-    "agci": "./dist/cli.mjs"
+    "ag": "./dist/cli.mjs"
   },
   "main": "./dist/cli.mjs",
   "types": "./dist/cli.d.mts",
@@ -17,14 +13,20 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "package.json",
+    "README.md"
   ],
   "dependencies": {
-    "commander": "13.1.0"
+    "commander": "13.1.0",
+    "concurrently": "^9.2.1",
+    "prompts": "^2.4.2",
+    "smol-toml": "^1.6.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
     "@types/node": "24.10.4",
+    "@types/prompts": "^2.4.9",
     "husky": "^9.1.7",
     "tsdown": "^0.18.2",
     "typescript": "^5.9.3",