@agentrules/cli 0.0.11 → 0.0.12

package/README.md

@@ -34,7 +34,8 @@ agentrules add <preset> --platform <platform> [options]
 | `-g, --global` | Install to global config directory |
 | `--dir <path>` | Install to a custom directory |
 | `-r, --registry <alias>` | Use a specific registry |
-| `-f, --force` | Overwrite existing files |
+| `-f, --force` | Overwrite existing files (backs up originals to `.bak`) |
+| `--no-backup` | Don't backup files before overwriting (use with `--force`) |
 | `--dry-run` | Preview changes without writing |
 | `--skip-conflicts` | Skip files that already exist |
 
@@ -200,12 +201,32 @@ agentrules publish --dry-run
 
 **Versioning:** Presets use `MAJOR.MINOR` versioning. You set the major version, and the registry auto-increments the minor version on each publish.
 
-### `agentrules unpublish <slug> <platform> <version>`
+### `agentrules unpublish <preset>`
 
 Remove a specific version of a preset from the registry. Requires authentication.
 
 ```bash
-agentrules unpublish my-preset opencode 1.0
+agentrules unpublish <preset> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-p, --platform <platform>` | Target platform (if not in preset string) |
+| `-V, --version <version>` | Version to unpublish (if not in preset string) |
+
+**Examples:**
+
+```bash
+# Full format: slug.platform@version
+agentrules unpublish my-preset.opencode@1.0
+
+# With flags
+agentrules unpublish my-preset --platform opencode --version 1.0
+
+# Mixed: version in string, platform as flag
+agentrules unpublish my-preset@1.0 --platform opencode
 ```
 
 **Note:** Unpublished versions cannot be republished with the same version number.

package/dist/index.js

@@ -8,7 +8,7 @@ import { promisify } from "util";
 import * as client from "openid-client";
 import chalk from "chalk";
 import { chmod, constants } from "fs";
-import { access, constants as constants$1, mkdir, readFile, readdir, rm, stat, writeFile } from "fs/promises";
+import { access, constants as constants$1, copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "fs/promises";
 import { homedir } from "os";
 import * as p from "@clack/prompts";
 
@@ -221,6 +221,14 @@ function fileStatus(status, filePath, options = {}) {
 	return `${config.style(config.symbol)} ${config.style(pad(label, 14))} ${filePath}`;
 }
 /**
+* Format a backup status line
+* e.g., "↪ backed up    .opencode/AGENT_RULES.md → .opencode/AGENT_RULES.md.bak"
+*/
+function backupStatus(originalPath, backupPath, options = {}) {
+	const label = options.dryRun ? "would backup" : "backed up";
+	return `${theme.info("↪")} ${theme.info(pad(label, 14))} ${originalPath} ${symbols.arrow} ${backupPath}`;
+}
+/**
 * Step indicator for multi-step operations
 * e.g., "[1/3] Fetching registry..."
 */
@@ -335,6 +343,7 @@ const ui = {
 	warning,
 	info: info$1,
 	fileStatus,
+	backupStatus,
 	step,
 	brand,
 	banner,
@@ -1209,6 +1218,7 @@ async function addPreset(options) {
 	const writeStats = await writeBundleFiles(bundle, target, {
 		force: Boolean(options.force),
 		skipConflicts: Boolean(options.skipConflicts),
+		noBackup: Boolean(options.noBackup),
 		dryRun
 	});
 	return {
@@ -1216,6 +1226,7 @@ async function addPreset(options) {
 		bundle,
 		files: writeStats.files,
 		conflicts: writeStats.conflicts,
+		backups: writeStats.backups,
 		targetRoot: target.root,
 		targetLabel: target.label,
 		registryAlias,
@@ -1298,6 +1309,7 @@ function resolveInstallTarget(platform, options) {
 async function writeBundleFiles(bundle, target, behavior) {
 	const files = [];
 	const conflicts = [];
+	const backups = [];
 	if (!behavior.dryRun) await mkdir(target.root, { recursive: true });
 	for (const file of bundle.files) {
 		const decoded = decodeBundledFile(file);
@@ -1326,6 +1338,16 @@ async function writeBundleFiles(bundle, target, behavior) {
 			continue;
 		}
 		if (behavior.force) {
+			if (!behavior.noBackup) {
+				const backupPath = `${destination}.bak`;
+				const relativeBackupPath = `${relativePath}.bak`;
+				if (!behavior.dryRun) await copyFile(destination, backupPath);
+				backups.push({
+					originalPath: relativePath,
+					backupPath: relativeBackupPath
+				});
+				log.debug(`Backed up: ${relativePath} → ${relativeBackupPath}`);
+			}
 			if (!behavior.dryRun) await writeFile(destination, data);
 			files.push({
 				path: relativePath,
@@ -1346,7 +1368,8 @@ async function writeBundleFiles(bundle, target, behavior) {
 	}
 	return {
 		files,
-		conflicts
+		conflicts,
+		backups
 	};
 }
 /**
@@ -1621,6 +1644,66 @@ async function detectPlatforms(directory) {
 	return detected;
 }
 /**
+* Resolve the target platform directory for initialization.
+*
+* Detection order (deterministic):
+* 1. If targetDir itself is a platform directory (e.g., ".claude"), use it directly
+* 2. Otherwise, detect platform directories inside targetDir
+*
+* @param targetDir - The target directory (cwd or user-provided path)
+* @param platformOverride - Optional platform to use instead of detecting/inferring
+*/
+async function resolvePlatformDirectory(targetDir, platformOverride) {
+	const targetDirName = basename(targetDir);
+	const targetPlatform = getPlatformFromDir(targetDirName);
+	if (targetPlatform) {
+		const platform$1 = platformOverride ? normalizePlatform(platformOverride) : targetPlatform;
+		return {
+			platformDir: targetDir,
+			platform: platform$1,
+			isTargetPlatformDir: true,
+			detected: []
+		};
+	}
+	const detected = await detectPlatforms(targetDir);
+	let platform;
+	let platformDir;
+	if (platformOverride) {
+		platform = normalizePlatform(platformOverride);
+		const detectedPath = detected.find((d) => d.id === platform)?.path;
+		platformDir = detectedPath ? join(targetDir, detectedPath) : join(targetDir, PLATFORMS[platform].projectDir);
+	} else if (detected.length > 0) {
+		platform = detected[0].id;
+		platformDir = join(targetDir, detected[0].path);
+	} else {
+		platform = "opencode";
+		platformDir = join(targetDir, PLATFORMS.opencode.projectDir);
+	}
+	return {
+		platformDir,
+		platform,
+		isTargetPlatformDir: false,
+		detected
+	};
+}
+/**
+* Check if --platform flag is required for non-interactive mode.
+* Returns the reason if required, so CLI can show appropriate error.
+*/
+function requiresPlatformFlag(resolved) {
+	if (resolved.isTargetPlatformDir) return { required: false };
+	if (resolved.detected.length === 0) return {
+		required: true,
+		reason: "no_platforms"
+	};
+	if (resolved.detected.length > 1) return {
+		required: true,
+		reason: "multiple_platforms",
+		platforms: resolved.detected.map((d) => d.id)
+	};
+	return { required: false };
+}
+/**
 * Initialize a preset in a platform directory.
 *
 * Structure:
@@ -1704,30 +1787,36 @@ async function initInteractive(options) {
 	let selectedPlatform;
 	if (explicitPlatformDir) {
 		targetPlatformDir = explicitPlatformDir;
-		const dirName = explicitPlatformDir.split("/").pop() ?? explicitPlatformDir;
+		const dirName = basename(explicitPlatformDir);
 		selectedPlatform = platformOption ?? getPlatformFromDir(dirName) ?? "opencode";
 	} else {
-		const detected = await detectPlatforms(baseDir);
-		const detectedMap = new Map(detected.map((d) => [d.id, d]));
-		if (detected.length > 0) p.note(detected.map((d) => `${d.id} → ${d.path}`).join("\n"), "Detected platform directories");
-		const defaultPlatform = platformOption ?? (detected.length > 0 ? detected[0].id : "opencode");
-		const platformChoice = await p.select({
-			message: "Platform",
-			options: PLATFORM_IDS.map((id) => ({
-				value: id,
-				label: detectedMap.has(id) ? `${id} (detected)` : id,
-				hint: detectedMap.get(id)?.path
-			})),
-			initialValue: defaultPlatform
-		});
-		if (p.isCancel(platformChoice)) {
-			p.cancel("Cancelled");
-			process.exit(0);
+		const resolved = await resolvePlatformDirectory(baseDir, platformOption);
+		if (resolved.isTargetPlatformDir) {
+			targetPlatformDir = resolved.platformDir;
+			selectedPlatform = resolved.platform;
+			p.note(`Detected platform directory: ${resolved.platform}`, "Using current directory");
+		} else {
+			const detectedMap = new Map(resolved.detected.map((d) => [d.id, d]));
+			if (resolved.detected.length > 0) p.note(resolved.detected.map((d) => `${d.id} → ${d.path}`).join("\n"), "Detected platform directories");
+			const platformChoice = await p.select({
+				message: "Platform",
+				options: PLATFORM_IDS.map((id) => ({
+					value: id,
+					label: detectedMap.has(id) ? `${id} (detected)` : id,
+					hint: detectedMap.get(id)?.path
+				})),
+				initialValue: resolved.platform
+			});
+			if (p.isCancel(platformChoice)) {
+				p.cancel("Cancelled");
+				process.exit(0);
+			}
+			selectedPlatform = platformChoice;
+			if (selectedPlatform !== resolved.platform) {
+				const reResolved = await resolvePlatformDirectory(baseDir, selectedPlatform);
+				targetPlatformDir = reResolved.platformDir;
+			} else targetPlatformDir = resolved.platformDir;
 		}
-		selectedPlatform = platformChoice;
-		const detectedInfo = detectedMap.get(selectedPlatform);
-		if (detectedInfo) targetPlatformDir = join(baseDir, detectedInfo.path);
-		else targetPlatformDir = join(baseDir, PLATFORMS[selectedPlatform].projectDir);
 	}
 	const configPath = join(targetPlatformDir, PRESET_CONFIG_FILENAME);
 	if (!force && await fileExists(configPath)) {
@@ -2139,10 +2228,45 @@ async function discoverPresetDirs(inputDir) {
 //#endregion
 //#region src/commands/unpublish.ts
 /**
+* Parses preset input to extract slug, platform, and version.
+* Supports formats:
+* - "my-preset.claude@1.0" (platform and version in string)
+* - "my-preset@1.0" (requires explicit platform)
+* - "my-preset.claude" (requires explicit version)
+*
+* Explicit --platform and --version flags take precedence.
+*/
+function parseUnpublishInput(input, explicitPlatform, explicitVersion) {
+	let normalized = input.toLowerCase().trim();
+	let parsedVersion;
+	const atIndex = normalized.lastIndexOf("@");
+	if (atIndex > 0) {
+		parsedVersion = normalized.slice(atIndex + 1);
+		normalized = normalized.slice(0, atIndex);
+	}
+	const version$1 = explicitVersion ?? parsedVersion;
+	const parts = normalized.split(".");
+	const maybePlatform = parts.at(-1);
+	let slug;
+	let platform;
+	if (maybePlatform && isSupportedPlatform(maybePlatform)) {
+		slug = parts.slice(0, -1).join(".");
+		platform = explicitPlatform ?? maybePlatform;
+	} else {
+		slug = normalized;
+		platform = explicitPlatform;
+	}
+	return {
+		slug,
+		platform,
+		version: version$1
+	};
+}
+/**
 * Unpublishes a preset version from the registry
 */
 async function unpublish(options) {
-	const { slug, platform, version: version$1 } = options;
+	const { slug, platform, version: version$1 } = parseUnpublishInput(options.preset, options.platform, options.version);
 	if (!slug) {
 		log.error("Preset slug is required");
 		return {
@@ -2151,14 +2275,14 @@ async function unpublish(options) {
 		};
 	}
 	if (!platform) {
-		log.error("Platform is required");
+		log.error("Platform is required. Use --platform or specify as <slug>.<platform>@<version>");
 		return {
 			success: false,
 			error: "Platform is required"
 		};
 	}
 	if (!version$1) {
-		log.error("Version is required");
+		log.error("Version is required. Use --version or specify as <slug>.<platform>@<version>");
 		return {
 			success: false,
 			error: "Version is required"
@@ -2217,7 +2341,7 @@ program.name("agentrules").description("The AI Agent Directory CLI").version(pac
 		log.debug(`Failed to init context: ${getErrorMessage(error$2)}`);
 	}
 }).showHelpAfterError();
-program.command("add <preset>").description("Download and install a preset from the registry").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Install a specific version").option("-r, --registry <alias>", "Use a specific registry alias").option("-g, --global", "Install to global directory").option("--dir <path>", "Install to a custom directory").option("-f, --force", "Overwrite existing files").option("-y, --yes", "Alias for --force").option("--dry-run", "Preview changes without writing").option("--skip-conflicts", "Skip conflicting files").action(handle(async (preset, options) => {
+program.command("add <preset>").description("Download and install a preset from the registry").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Install a specific version").option("-r, --registry <alias>", "Use a specific registry alias").option("-g, --global", "Install to global directory").option("--dir <path>", "Install to a custom directory").option("-f, --force", "Overwrite existing files (backs up originals)").option("-y, --yes", "Alias for --force").option("--dry-run", "Preview changes without writing").option("--skip-conflicts", "Skip conflicting files").option("--no-backup", "Don't backup files before overwriting (use with --force)").action(handle(async (preset, options) => {
 	const platform = options.platform ? normalizePlatformInput(options.platform) : void 0;
 	const dryRun = Boolean(options.dryRun);
 	const spinner$1 = await log.spinner("Fetching preset...");
@@ -2231,7 +2355,8 @@ program.command("add <preset>").description("Download and install a preset from
 			directory: options.dir,
 			force: Boolean(options.force || options.yes),
 			dryRun,
-			skipConflicts: Boolean(options.skipConflicts)
+			skipConflicts: Boolean(options.skipConflicts),
+			noBackup: options.backup === false
 		});
 	} catch (err) {
 		spinner$1.stop();
@@ -2241,16 +2366,23 @@ program.command("add <preset>").description("Download and install a preset from
 	const hasBlockingConflicts = result.conflicts.length > 0 && !options.skipConflicts && !dryRun;
 	if (hasBlockingConflicts) {
 		const count$1 = result.conflicts.length === 1 ? "1 file has" : `${result.conflicts.length} files have`;
-		log.error(`${count$1} conflicts. Use ${ui.command("--force")} to overwrite.`);
+		const forceHint = `Use ${ui.command("--force")} to overwrite ${ui.muted("(--no-backup to skip backups)")}`;
+		log.error(`${count$1} conflicts. ${forceHint}`);
 		log.print("");
 		for (const conflict of result.conflicts.slice(0, 3)) {
 			log.print(`  ${ui.muted("•")} ${conflict.path}`);
 			if (conflict.diff) log.print(conflict.diff.split("\n").map((l) => `    ${l}`).join("\n"));
 		}
 		if (result.conflicts.length > 3) log.print(`\n  ${ui.muted(`...and ${result.conflicts.length - 3} more`)}`);
+		log.print("");
+		log.print(forceHint);
 		process.exitCode = 1;
 		return;
 	}
+	if (result.backups.length > 0) {
+		log.print("");
+		for (const backup of result.backups) log.print(ui.backupStatus(backup.originalPath, backup.backupPath, { dryRun }));
+	}
 	log.print("");
 	for (const file of result.files) {
 		const status = file.status === "overwritten" ? "updated" : file.status;
@@ -2291,25 +2423,23 @@ program.command("init").description("Initialize a new preset").argument("[direct
 		log.print(ui.numberedList(nextSteps$1));
 		return;
 	}
-	const targetDirName = basename(targetDir);
-	const targetIsPlatformDir = getPlatformFromDir(targetDirName);
-	let platformDir;
-	let platform;
-	if (targetIsPlatformDir) {
-		platformDir = targetDir;
-		platform = options.platform ?? targetIsPlatformDir;
-	} else {
-		const detected = await detectPlatforms(targetDir);
-		platform = options.platform ?? detected[0]?.id ?? "opencode";
-		const detectedPath = detected.find((d) => d.id === platform)?.path;
-		platformDir = detectedPath ? join(targetDir, detectedPath) : join(targetDir, PLATFORMS[platform].projectDir);
+	const resolved = await resolvePlatformDirectory(targetDir, options.platform);
+	if (!options.platform) {
+		const check$1 = requiresPlatformFlag(resolved);
+		if (check$1.required) {
+			if (check$1.reason === "no_platforms") {
+				const targetDirName = basename(targetDir);
+				log.error(`No platform directory found in "${targetDirName}". Specify --platform (${PLATFORM_IDS.join(", ")}) or run from a platform directory.`);
+			} else log.error(`Multiple platform directories found (${check$1.platforms.join(", ")}). Specify --platform to choose one.`);
+			process.exit(1);
+		}
 	}
 	const result = await initPreset({
-		directory: platformDir,
+		directory: resolved.platformDir,
 		name: options.name ?? defaultName,
 		title: options.title,
 		description: options.description,
-		platform,
+		platform: resolved.platform,
 		license: options.license,
 		force: options.force
 	});
@@ -2464,11 +2594,12 @@ program.command("publish").description("Publish a preset to the registry").argum
 	});
 	if (!result.success) process.exitCode = 1;
 }));
-program.command("unpublish").description("Remove a preset version from the registry").argument("<slug>", "Preset slug (e.g., my-preset)").argument("<platform>", "Platform (e.g., opencode, claude)").argument("<version>", "Version to unpublish (e.g., 1.1, 2.3)").action(handle(async (slug, platform, version$1) => {
+program.command("unpublish").description("Remove a preset version from the registry").argument("<preset>", "Preset to unpublish (e.g., my-preset.claude@1.0 or my-preset@1.0)").option("-p, --platform <platform>", "Target platform (opencode, codex, claude, cursor)").option("-V, --version <version>", "Version to unpublish").action(handle(async (preset, options) => {
+	const platform = options.platform ? normalizePlatformInput(options.platform) : void 0;
 	const result = await unpublish({
-		slug,
+		preset,
 		platform,
-		version: version$1
+		version: options.version
 	});
 	if (!result.success) process.exitCode = 1;
 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrules/cli",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "author": "Brian Cheung <bcheung.dev@gmail.com> (https://github.com/bcheung)",
   "license": "MIT",
   "homepage": "https://agentrules.directory",