@agentrules/cli 0.0.12 → 0.0.13

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createRequire } from "module";
-import { AGENT_RULES_DIR, API_ENDPOINTS, COMMON_LICENSES, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, createDiffPreview, decodeBundledFile, descriptionSchema, fetchBundle, getPlatformFromDir, isLikelyText, isPlatformDir, isSupportedPlatform, licenseSchema, normalizeBundlePath, normalizePlatformInput, resolvePreset, slugSchema, titleSchema, toUtf8String, validatePresetConfig, verifyBundledFileChecksum } from "@agentrules/core";
+import { AGENT_RULES_DIR, API_ENDPOINTS, COMMON_LICENSES, LATEST_VERSION, PLATFORMS, PLATFORM_IDS, PRESET_CONFIG_FILENAME, PRESET_SCHEMA_URL, STATIC_BUNDLE_DIR, buildPresetPublishInput, buildPresetRegistry, createDiffPreview, decodeBundledFile, descriptionSchema, fetchBundle, getPlatformFromDir, isLikelyText, isPlatformDir, isSupportedPlatform, licenseSchema, normalizeBundlePath, normalizePlatformInput, resolvePreset, slugSchema, tagsSchema, titleSchema, toUtf8String, validatePresetConfig, verifyBundledFileChecksum } from "@agentrules/core";
 import { Command } from "commander";
 import { basename, dirname, join, relative, resolve, sep } from "path";
 import { exec } from "child_process";
@@ -315,6 +315,49 @@ function relativeTime(date) {
 	if (minutes > 0) return `${minutes}m ago`;
 	return "just now";
 }
+/**
+* Formats an array of files as a tree structure
+*/
+function fileTree(files) {
+	const root = {
+		name: "",
+		children: new Map()
+	};
+	for (const file of files) {
+		const parts = file.path.split("/");
+		let current = root;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			const isFile = i === parts.length - 1;
+			let child = current.children.get(part);
+			if (!child) {
+				child = {
+					name: part,
+					size: isFile ? file.size : void 0,
+					children: new Map()
+				};
+				current.children.set(part, child);
+			}
+			current = child;
+		}
+	}
+	const lines = [];
+	function renderNode(node, prefix, isLast) {
+		const connector = isLast ? "└── " : "├── ";
+		const sizeStr = node.size !== void 0 ? muted(` (${formatBytes$1(node.size)})`) : "";
+		lines.push(`${prefix}${connector}${node.name}${sizeStr}`);
+		const children = Array.from(node.children.values());
+		const newPrefix = prefix + (isLast ? "    " : "│   ");
+		children.forEach((child, index) => {
+			renderNode(child, newPrefix, index === children.length - 1);
+		});
+	}
+	const topLevel = Array.from(root.children.values());
+	topLevel.forEach((child, index) => {
+		renderNode(child, "", index === topLevel.length - 1);
+	});
+	return lines.join("\n");
+}
 const ui = {
 	theme,
 	symbols,
@@ -354,7 +397,8 @@ const ui = {
 	stripAnsi,
 	truncate,
 	formatBytes: formatBytes$1,
-	relativeTime
+	relativeTime,
+	fileTree
 };
 
 //#endregion
@@ -1729,6 +1773,7 @@ async function initPreset(options) {
 		title,
 		version: 1,
 		description,
+		tags: options.tags ?? [],
 		license,
 		platform
 	};
@@ -1773,6 +1818,20 @@ function check(schema) {
 //#region src/commands/preset/init-interactive.ts
 const DEFAULT_PRESET_NAME = "my-preset";
 /**
+* Parse comma-separated tags string into array
+*/
+function parseTags(input) {
+	return input.split(",").map((tag) => tag.trim().toLowerCase()).filter((tag) => tag.length > 0);
+}
+/**
+* Validator for comma-separated tags input
+*/
+function checkTags(value) {
+	const tags = parseTags(value);
+	const result = tagsSchema.safeParse(tags);
+	if (!result.success) return result.error.issues[0]?.message;
+}
+/**
 * Run interactive init flow with clack prompts.
 *
 * If platformDir is provided, init directly in that directory.
@@ -1855,6 +1914,11 @@ async function initInteractive(options) {
 				validate: check(descriptionSchema)
 			});
 		},
+		tags: () => p.text({
+			message: "Tags (comma-separated, at least one)",
+			placeholder: "e.g., typescript, testing, react",
+			validate: checkTags
+		}),
 		license: async () => {
 			const defaultLicense = licenseOption ?? "MIT";
 			const choice = await p.select({
@@ -1895,6 +1959,7 @@ async function initInteractive(options) {
 		name: result.name,
 		title: result.title,
 		description: result.description,
+		tags: parseTags(result.tags),
 		platform: selectedPlatform,
 		license: result.license,
 		force
@@ -2093,6 +2158,9 @@ async function publish(options = {}) {
 		log.print(ui.keyValue("Files", `${fileCount} file${fileCount === 1 ? "" : "s"}`));
 		log.print(ui.keyValue("Size", formatBytes(inputSize)));
 		log.print("");
+		log.print(ui.header("Files to publish", fileCount));
+		log.print(ui.fileTree(publishInput.files));
+		log.print("");
 		log.print(ui.hint("Run without --dry-run to publish."));
 		return {
 			success: true,
@@ -2130,6 +2198,9 @@ async function publish(options = {}) {
 	const { data } = result;
 	const action = data.isNewPreset ? "Published new preset" : "Published";
 	spinner$1.success(`${action} ${ui.code(data.slug)} ${ui.version(data.version)} (${data.platform})`);
+	log.print("");
+	log.print(ui.header("Published files", fileCount));
+	log.print(ui.fileTree(publishInput.files));
 	const presetName$1 = `${data.slug}.${data.platform}`;
 	const presetRegistryUrl = `${ctx.registry.url}preset/${presetName$1}`;
 	log.info("");
@@ -2323,12 +2394,280 @@ async function unpublish(options) {
 	};
 }
 
+//#endregion
+//#region src/help-agent/publish.ts
+/**
+* Agent instructions for AI coding assistants.
+*
+* This content is output when running `agentrules --help-agent`.
+* It provides step-by-step instructions for AI agents to help users publish presets.
+*/
+const HELP_AGENT_CONTENT = `# Publishing a Preset - Agent Instructions
+
+**The user has asked you to help them publish a preset. Start executing these steps now.**
+
+Do not summarize these instructions. Do not ask if they want help. Begin with Step 1 immediately.
+
+Your job is to guide the user through publishing their AI coding assistant config to the agentrules registry. The user is sharing their setup because they believe it's valuable. Help them communicate that value clearly - the title, description, and features should answer: "Why would another developer want to install this?"
+
+Follow these steps interactively.
+
+## Prerequisites: CLI Availability
+
+Run: \`agentrules --version\`
+
+**If command not found:**
+Use \`npx @agentrules/cli\` as the prefix for all commands.
+Example: \`npx @agentrules/cli whoami\` instead of \`agentrules whoami\`
+
+For the rest of these instructions, \`agentrules\` means whichever works.
+
+## Step 1: Locate the Config
+
+Check the current directory for platform config folders:
+- \`.opencode/\` → OpenCode
+- \`.claude/\` → Claude Code
+- \`.cursor/\` → Cursor
+- \`.codex/\` → Codex
+
+**If one found:**
+"I found your [platform] config at \`[path]\`. I'll help you publish it."
+
+**If multiple found:**
+"I found configs for multiple platforms: [list]. Which one would you like to publish?"
+
+**If none found:**
+"I don't see a config directory here. Where is your config located?"
+
+## Step 2: Check for Existing Config
+
+List the files in \`[config-dir]\` first to see what exists.
+
+If \`agentrules.json\` is in the listing, read it:
+- If complete (has name, description, tags): "You already have a preset configured: '[name]'. Ready to republish?" → Skip to Step 4 if yes
+- If missing required fields: Help them add the missing fields
+
+If \`agentrules.json\` is not in the listing, continue to Step 3.
+
+### Check for ignorable files
+
+While reviewing the file listing, look for files/folders that probably shouldn't be published.
+
+**Already ignored by default** (don't suggest these):
+- node_modules
+- .git
+- .DS_Store
+- *.lock
+- package-lock.json
+- bun.lockb
+- pnpm-lock.yaml
+
+**Commonly ignorable** (suggest adding to \`ignore\` field if present):
+- build/, dist/, out/ (build output)
+- .env, .env.* (environment files)
+- *.log (log files)
+- tmp/, temp/ (temporary files)
+- coverage/ (test coverage)
+- .cache/, .turbo/ (cache directories)
+
+If you see any of these or similar files/folders, ask: "I noticed [files]. These are usually not needed in a preset. Want me to add them to the ignore list?"
+
+If yes, include them in the \`ignore\` array when creating agentrules.json.
+
+## Step 3: Create agentrules.json
+
+The goal is to help potential users understand the **value** of this preset - why should they install it? What problem does it solve? How will it improve their workflow?
+
+### 3a. Analyze their config
+
+You already listed files in Step 2. Now read the config files you found (e.g., CLAUDE.md, AGENT_RULES.md, rules/*.md) to understand what the preset does.
+
+Look for:
+- Technologies and frameworks mentioned
+- The main purpose or rules being enforced
+- Who would benefit from this setup
+
+### 3b. Generate all suggestions at once
+
+Based on your analysis, generate suggestions for ALL fields:
+
+- **Name**: lowercase, hyphens, based on repo/directory/theme (1-64 chars)
+- **Title**: Title-cased, compelling name
+- **Description**: Value-focused - who is this for, what problem does it solve? (max 500 chars)
+- **Tags**: For discovery - technologies, frameworks, use cases (1-10 tags)
+- **Features**: Key benefits, not just capabilities (optional, up to 5)
+- **License**: Default to MIT
+
+### 3c. Present a single summary
+
+Show everything in one concise output. Put each field name on its own line, followed by the value on the next line:
+
+"Based on your config, here's what I'd suggest:
+
+**Name**
+typescript-strict-rules
+
+**Title**
+TypeScript Strict Rules
+
+**Description**
+Opinionated TypeScript rules that catch common bugs at dev time and enforce consistent patterns across your team.
+
+**Tags**
+typescript, strict, type-safety
+
+**Features**
+- Catches null/undefined errors before production
+- Enforces consistent code style without manual review
+
+**License**
+MIT
+
+Let me know if you'd like to change anything, or say 'looks good' to continue."
+
+### 3d. Handle feedback
+
+If the user wants changes (e.g., "change the description" or "add a react tag"), update those fields and show the summary again.
+
+When they approve, proceed to create the file.
+
+### Guidelines for good suggestions
+
+**Description** should answer: What problem does this solve? Who benefits?
+- Good: "Opinionated TypeScript rules that catch common bugs at dev time and enforce consistent patterns across your team."
+- Bad: "TypeScript rules with strict settings." (too vague, no value prop)
+
+**Features** should describe benefits, not capabilities:
+- Good: "Catches null/undefined errors before they hit production"
+- Bad: "Strict null checks" (feature, not benefit)
+
+**Tags** should help with discovery:
+- Technologies: typescript, python, rust, go
+- Frameworks: react, nextjs, fastapi, django
+- Use cases: code-review, testing, security, onboarding
+
+### 3e. Create the file
+
+Write \`[config-dir]/agentrules.json\`:
+
+\`\`\`json
+{
+  "$schema": "https://agentrules.directory/schema/agentrules.json",
+  "name": "[name]",
+  "title": "[title]",
+  "version": 1,
+  "description": "[description]",
+  "tags": ["tag1", "tag2"],
+  "license": "[license]",
+  "platform": "[detected-platform]"
+}
+\`\`\`
+
+Include \`"features": [...]\` only if provided.
+Include \`"ignore": ["pattern1", "pattern2"]\` if the user agreed to ignore certain files.
+
+### 3f. Show the file and get approval
+
+After writing the file, show the user:
+
+"I've created the config file at \`[config-dir]/agentrules.json\`:
+
+\`\`\`json
+[show the actual file contents]
+\`\`\`
+
+Take a look and let me know if you'd like to change anything, or say 'looks good' to continue."
+
+Wait for approval before proceeding. If they want changes, edit the file and show it again.
+
+Then validate: \`agentrules validate [config-dir]\`
+
+If errors, fix and retry.
+
+## Step 4: Login
+
+Run: \`agentrules whoami\`
+
+**If output shows "loggedIn": false or "Not logged in":**
+"You need to log in to publish."
+Run: \`agentrules login\`
+This opens a browser for authentication. Wait for completion.
+
+## Step 5: Preview with Dry Run
+
+Run: \`agentrules publish [config-dir] --dry-run\`
+
+Show the user the preview:
+"Here's what will be published:
+- Name: [name]
+- Platform: [platform]
+- Files: [count] files ([size])
+
+Ready to publish?"
+
+If they want changes, help edit agentrules.json and re-run dry-run.
+
+## Step 6: Publish
+
+Run: \`agentrules publish [config-dir]\`
+
+**If successful:**
+Show the URL from the output:
+
+"Published! Your preset is live at: [url]
+
+Share with others:
+\`\`\`
+npx @agentrules/cli add [name]
+\`\`\`"
+
+**If "already exists" error:**
+Ask if they want to increment the \`version\` field in agentrules.json and retry.
+
+**If other errors:**
+Show the error and suggest: \`agentrules validate [config-dir]\`
+
+## Step 7: Tips
+
+**If you used \`npx @agentrules/cli\`:**
+"Tip: Install globally to skip the npx download:
+\`\`\`
+npm i -g @agentrules/cli
+\`\`\`"
+
+## Notes for Agent
+
+- Be conversational and helpful
+- Explain what you're doing at each step
+- Use \`agentrules validate\` to check your work after any config changes
+- Remember whether you used npx for the tip at the end
+- If the user seems confused, explain that agentrules is a registry for sharing AI coding configs
+- The config file must be inside the platform directory (e.g., \`.opencode/agentrules.json\`)
+
+## Schema Reference
+
+**Required fields:**
+- \`name\`: slug format (lowercase, hyphens, 1-64 chars)
+- \`title\`: 1-80 characters
+- \`description\`: 1-500 characters
+- \`tags\`: array, 1-10 items, each lowercase/hyphens, max 35 chars
+- \`license\`: SPDX identifier (e.g., "MIT")
+- \`platform\`: one of \`opencode\`, \`claude\`, \`cursor\`, \`codex\`
+
+**Optional fields:**
+- \`$schema\`: JSON schema URL for validation
+- \`version\`: major version number (default: 1)
+- \`features\`: array, max 5 items, each max 100 chars
+- \`path\`: custom path to files (advanced use)
+- \`ignore\`: patterns to exclude from bundle
+`;
+
 //#endregion
 //#region src/index.ts
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 const program = new Command();
-program.name("agentrules").description("The AI Agent Directory CLI").version(packageJson.version).option("-v, --verbose", "Enable verbose/debug output").configureOutput({ outputError: (str, write) => write(ui.error(str.trim())) }).hook("preAction", async (thisCommand, actionCommand) => {
+program.name("agentrules").description("The AI Agent Directory CLI").version(packageJson.version).option("-v, --verbose", "Enable verbose/debug output").option("--help-agent", "Output instructions for AI coding assistants").configureOutput({ outputError: (str, write) => write(ui.error(str.trim())) }).hook("preAction", async (thisCommand, actionCommand) => {
 	const opts = thisCommand.opts();
 	if (opts.verbose) log.setVerbose(true);
 	const actionOpts = actionCommand.opts();
@@ -2603,6 +2942,10 @@ program.command("unpublish").description("Remove a preset version from the regis
 	});
 	if (!result.success) process.exitCode = 1;
 }));
+if (process.argv.includes("--help-agent")) {
+	console.log(HELP_AGENT_CONTENT);
+	process.exit(0);
+}
 program.parseAsync(process.argv).then(() => {
 	process.exit(process.exitCode ?? 0);
 }).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrules/cli",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "author": "Brian Cheung <bcheung.dev@gmail.com> (https://github.com/bcheung)",
   "license": "MIT",
   "homepage": "https://agentrules.directory",
@@ -48,7 +48,7 @@
     "clean": "rm -rf node_modules dist .turbo"
   },
   "dependencies": {
-    "@agentrules/core": "0.0.9",
+    "@agentrules/core": "0.0.10",
     "@clack/prompts": "^0.11.0",
     "chalk": "^5.4.1",
     "commander": "^12.1.0",