claudekit-cli 1.0.0 → 1.1.0

package/.github/workflows/ci.yml

@@ -5,10 +5,12 @@ on:
     branches:
       - main
       - master
+      - dev
   push:
     branches:
       - main
       - master
+      - dev
 
 jobs:
   test:

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.1.0](https://github.com/mrgoonie/claudekit-cli/compare/v1.0.1...v1.1.0) (2025-10-17)
+
+
+### Bug Fixes
+
+* format package.json keywords array to single line ([c8dd66f](https://github.com/mrgoonie/claudekit-cli/commit/c8dd66faa94a84188790947fe3ee6f562d63cd46))
+
+
+### Features
+
+* **cli:** add versions command to list available releases ([27fbad1](https://github.com/mrgoonie/claudekit-cli/commit/27fbad1be3b5df90cb85ba9a3dd1b0eeb4fa6125))
+
+## [1.0.1](https://github.com/mrgoonie/claudekit-cli/compare/v1.0.0...v1.0.1) (2025-10-09)
+
+
+### Bug Fixes
+
+* resolve CI lint failures ([8ff0186](https://github.com/mrgoonie/claudekit-cli/commit/8ff0186d8381003802c70c7cc17383e5662239a1))
+
 # 1.0.0 (2025-10-09)
 
 

package/CLAUDE.md

@@ -31,3 +31,10 @@ We keep all important docs in `./docs` folder and keep updating them, structure
 └── project-roadmap.md
 ```
 
+## Related directories
+
+- ClaudeKit CLI: current directory
+- ClaudeKit Engineer: `../claudekit-engineer`
+- ClaudeKit Marketing: `../claudekit-marketing`
+- ClaudeKit Website: `../claudekit-web`
+- ClaudeKit Docs: `../claudekit-docs`

package/README.md

@@ -13,14 +13,44 @@ Command-line tool for bootstrapping and updating ClaudeKit projects.
 - Secure credential storage using OS keychain
 - Beautiful CLI interface with interactive prompts
 
+## Prerequisites
+
+Before using ClaudeKit CLI, you need to:
+
+1. **Purchase a ClaudeKit Starter Kit** from [ClaudeKit.cc](https://claudekit.cc)
+2. **Get Repository Access**: After purchase, you'll receive access to the private GitHub repository containing your kit
+3. **Create a GitHub Personal Access Token** (PAT) with `repo` scope to download releases
+
+Without a purchased kit and repository access, the CLI will not be able to download any project templates.
+
 ## Installation
 
-### From npm (Recommended)
+The ClaudeKit CLI is published on npm at [npmjs.com/package/claudekit-cli](https://www.npmjs.com/package/claudekit-cli).
+
+### Using npm (Recommended)
+
+```bash
+npm install -g claudekit-cli
+```
+
+### Using Bun
 
 ```bash
 bun add -g claudekit-cli
 ```
 
+### Using Yarn
+
+```bash
+yarn global add claudekit-cli
+```
+
+### Using pnpm
+
+```bash
+pnpm add -g claudekit-cli
+```
+
 ### From Source
 
 ```bash
@@ -30,6 +60,12 @@ bun install
 bun link
 ```
 
+After installation, verify it's working:
+
+```bash
+ck --version
+```
+
 ## Usage
 
 ### Create a New Project
@@ -58,10 +94,27 @@ ck update --kit engineer
 ck update --kit engineer --version v1.0.0
 ```
 
+### List Available Versions
+
+```bash
+# Show all available versions for all kits
+ck versions
+
+# Filter by specific kit
+ck versions --kit engineer
+ck versions --kit marketing
+
+# Show more versions (default: 30)
+ck versions --limit 50
+
+# Include prereleases and drafts
+ck versions --all
+```
+
 ### Other Commands
 
 ```bash
-# Show version
+# Show CLI version
 ck --version
 ck -v
 
@@ -93,9 +146,13 @@ export GITHUB_TOKEN=ghp_your_token_here
 
 ## Available Kits
 
+ClaudeKit offers premium starter kits available for purchase at [ClaudeKit.cc](https://claudekit.cc):
+
 - **engineer**: ClaudeKit Engineer - Engineering toolkit for building with Claude
 - **marketing**: ClaudeKit Marketing - [Coming Soon]
 
+Each kit provides a comprehensive project template with best practices, tooling, and workflows optimized for Claude Code development.
+
 ## Configuration
 
 Configuration is stored in `~/.claudekit/config.json`:
@@ -193,7 +250,8 @@ claudekit-cli/
 ### 1. Commands
 - **`ck new`**: Create new project from release
 - **`ck update`**: Update existing project
-- **`ck --version`**: Show version
+- **`ck versions`**: List available versions of ClaudeKit repositories
+- **`ck --version`**: Show CLI version
 - **`ck --help`**: Show help
 
 ### 2. Authentication (Multi-Tier Fallback)

package/biome.json

@@ -1,5 +1,8 @@
 {
 	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"files": {
+		"ignore": ["dist", "node_modules", "*.log"]
+	},
 	"organizeImports": {
 		"enabled": true
 	},

package/dist/index.js

@@ -17718,6 +17718,11 @@ var UpdateCommandOptionsSchema = exports_external.object({
   kit: KitType.optional(),
   version: exports_external.string().optional()
 });
+var VersionCommandOptionsSchema = exports_external.object({
+  kit: KitType.optional(),
+  limit: exports_external.number().optional(),
+  all: exports_external.boolean().optional()
+});
 var ConfigSchema = exports_external.object({
   github: exports_external.object({
     token: exports_external.string().optional()
@@ -19085,6 +19090,100 @@ Protected files (.env, etc.) were not modified.`, "Update complete");
   }
 }
 
+// src/commands/version.ts
+var import_picocolors4 = __toESM(require_picocolors(), 1);
+function formatRelativeTime(dateString) {
+  if (!dateString)
+    return "Unknown";
+  const date = new Date(dateString);
+  const now = new Date;
+  const diffMs = now.getTime() - date.getTime();
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  if (diffDays === 0)
+    return "Today";
+  if (diffDays === 1)
+    return "Yesterday";
+  if (diffDays < 7)
+    return `${diffDays} days ago`;
+  if (diffDays < 30)
+    return `${Math.floor(diffDays / 7)} weeks ago`;
+  if (diffDays < 365)
+    return `${Math.floor(diffDays / 30)} months ago`;
+  return `${Math.floor(diffDays / 365)} years ago`;
+}
+function displayKitReleases(kitName, releases) {
+  console.log(`
+${import_picocolors4.default.bold(import_picocolors4.default.cyan(kitName))} - Available Versions:
+`);
+  if (releases.length === 0) {
+    console.log(import_picocolors4.default.dim("  No releases found"));
+    return;
+  }
+  for (const release of releases) {
+    const version = import_picocolors4.default.green(release.tag_name);
+    const name2 = release.name || "No title";
+    const publishedAt = formatRelativeTime(release.published_at);
+    const assetCount = release.assets.length;
+    const badges = [];
+    if (release.prerelease)
+      badges.push(import_picocolors4.default.yellow("[prerelease]"));
+    if (release.draft)
+      badges.push(import_picocolors4.default.gray("[draft]"));
+    const badgeStr = badges.length > 0 ? ` ${badges.join(" ")}` : "";
+    const versionPart = version.padEnd(20);
+    const namePart = name2.length > 40 ? `${name2.slice(0, 37)}...` : name2.padEnd(40);
+    const timePart = import_picocolors4.default.dim(publishedAt.padEnd(20));
+    const assetPart = import_picocolors4.default.dim(`(${assetCount} ${assetCount === 1 ? "asset" : "assets"})`);
+    console.log(`  ${versionPart}  ${namePart}  ${timePart}  ${assetPart}${badgeStr}`);
+  }
+  console.log(import_picocolors4.default.dim(`
+Showing ${releases.length} ${releases.length === 1 ? "release" : "releases"}`));
+}
+async function versionCommand(options) {
+  const prompts = new PromptsManager;
+  prompts.intro("\uD83D\uDCE6 ClaudeKit - Available Versions");
+  try {
+    const validOptions = VersionCommandOptionsSchema.parse(options);
+    const kitsToFetch = validOptions.kit ? [validOptions.kit] : Object.keys(AVAILABLE_KITS);
+    const github = new GitHubClient;
+    const limit = validOptions.limit || 30;
+    const releasePromises = kitsToFetch.map(async (kitType) => {
+      const kitConfig = AVAILABLE_KITS[kitType];
+      try {
+        const releases = await github.listReleases(kitConfig, limit);
+        const filteredReleases = validOptions.all ? releases : releases.filter((r2) => !r2.draft && !r2.prerelease);
+        return {
+          kitType,
+          kitConfig,
+          releases: filteredReleases,
+          error: null
+        };
+      } catch (error2) {
+        return {
+          kitType,
+          kitConfig,
+          releases: [],
+          error: error2 instanceof Error ? error2.message : "Unknown error"
+        };
+      }
+    });
+    const results = await Promise.all(releasePromises);
+    for (const result of results) {
+      if (result.error) {
+        console.log(`
+${import_picocolors4.default.bold(import_picocolors4.default.cyan(result.kitConfig.name))} - ${import_picocolors4.default.red("Error")}`);
+        console.log(import_picocolors4.default.dim(`  ${result.error}`));
+      } else {
+        displayKitReleases(result.kitConfig.name, result.releases);
+      }
+    }
+    prompts.outro("✨ Done");
+  } catch (error2) {
+    logger.error(error2 instanceof Error ? error2.message : "Unknown error occurred");
+    process.exit(1);
+  }
+}
+
 // src/index.ts
 var __dirname2 = fileURLToPath(new URL(".", import.meta.url));
 var packageJson = JSON.parse(readFileSync(join5(__dirname2, "../package.json"), "utf-8"));
@@ -19095,6 +19194,9 @@ cli.command("new", "Bootstrap a new ClaudeKit project").option("--dir <dir>", "T
 cli.command("update", "Update existing ClaudeKit project").option("--dir <dir>", "Target directory (default: .)").option("--kit <kit>", "Kit to use (engineer, marketing)").option("--version <version>", "Specific version to download (default: latest)").action(async (options) => {
   await updateCommand(options);
 });
+cli.command("versions", "List available versions of ClaudeKit repositories").option("--kit <kit>", "Filter by specific kit (engineer, marketing)").option("--limit <limit>", "Number of releases to show (default: 30)").option("--all", "Show all releases including prereleases").action(async (options) => {
+  await versionCommand(options);
+});
 cli.version(packageJson.version);
 cli.help();
 cli.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudekit-cli",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "CLI tool for bootstrapping and updating ClaudeKit projects",
 	"type": "module",
 	"bin": {

package/src/commands/version.ts

@@ -0,0 +1,135 @@
+import pc from "picocolors";
+import { GitHubClient } from "../lib/github.js";
+import { PromptsManager } from "../lib/prompts.js";
+import {
+	AVAILABLE_KITS,
+	type GitHubRelease,
+	type VersionCommandOptions,
+	VersionCommandOptionsSchema,
+} from "../types.js";
+import { logger } from "../utils/logger.js";
+
+/**
+ * Format a date as a relative time string
+ */
+function formatRelativeTime(dateString?: string): string {
+	if (!dateString) return "Unknown";
+
+	const date = new Date(dateString);
+	const now = new Date();
+	const diffMs = now.getTime() - date.getTime();
+	const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+	if (diffDays === 0) return "Today";
+	if (diffDays === 1) return "Yesterday";
+	if (diffDays < 7) return `${diffDays} days ago`;
+	if (diffDays < 30) return `${Math.floor(diffDays / 7)} weeks ago`;
+	if (diffDays < 365) return `${Math.floor(diffDays / 30)} months ago`;
+	return `${Math.floor(diffDays / 365)} years ago`;
+}
+
+/**
+ * Display releases for a single kit
+ */
+function displayKitReleases(kitName: string, releases: GitHubRelease[]): void {
+	console.log(`\n${pc.bold(pc.cyan(kitName))} - Available Versions:\n`);
+
+	if (releases.length === 0) {
+		console.log(pc.dim("  No releases found"));
+		return;
+	}
+
+	for (const release of releases) {
+		const version = pc.green(release.tag_name);
+		const name = release.name || "No title";
+		const publishedAt = formatRelativeTime(release.published_at);
+		const assetCount = release.assets.length;
+
+		// Add badges for prerelease and draft
+		const badges: string[] = [];
+		if (release.prerelease) badges.push(pc.yellow("[prerelease]"));
+		if (release.draft) badges.push(pc.gray("[draft]"));
+		const badgeStr = badges.length > 0 ? ` ${badges.join(" ")}` : "";
+
+		// Format: version  |  name  |  time  |  assets
+		const versionPart = version.padEnd(20);
+		const namePart = name.length > 40 ? `${name.slice(0, 37)}...` : name.padEnd(40);
+		const timePart = pc.dim(publishedAt.padEnd(20));
+		const assetPart = pc.dim(`(${assetCount} ${assetCount === 1 ? "asset" : "assets"})`);
+
+		console.log(`  ${versionPart}  ${namePart}  ${timePart}  ${assetPart}${badgeStr}`);
+	}
+
+	console.log(
+		pc.dim(`\nShowing ${releases.length} ${releases.length === 1 ? "release" : "releases"}`),
+	);
+}
+
+/**
+ * Version command - List available versions of ClaudeKit repositories
+ */
+export async function versionCommand(options: VersionCommandOptions): Promise<void> {
+	const prompts = new PromptsManager();
+
+	prompts.intro("📦 ClaudeKit - Available Versions");
+
+	try {
+		// Validate and parse options
+		const validOptions = VersionCommandOptionsSchema.parse(options);
+
+		// Determine which kits to fetch
+		const kitsToFetch = validOptions.kit
+			? [validOptions.kit]
+			: (Object.keys(AVAILABLE_KITS) as Array<keyof typeof AVAILABLE_KITS>);
+
+		// Initialize GitHub client
+		const github = new GitHubClient();
+
+		// Determine limit (default to 30, similar to GitHub CLI)
+		const limit = validOptions.limit || 30;
+
+		// Fetch releases for all requested kits in parallel
+		const releasePromises = kitsToFetch.map(async (kitType) => {
+			const kitConfig = AVAILABLE_KITS[kitType];
+			try {
+				const releases = await github.listReleases(kitConfig, limit);
+
+				// Filter out drafts and prereleases unless --all flag is set
+				const filteredReleases = validOptions.all
+					? releases
+					: releases.filter((r) => !r.draft && !r.prerelease);
+
+				return {
+					kitType,
+					kitConfig,
+					releases: filteredReleases,
+					error: null,
+				};
+			} catch (error) {
+				return {
+					kitType,
+					kitConfig,
+					releases: [],
+					error: error instanceof Error ? error.message : "Unknown error",
+				};
+			}
+		});
+
+		const results = await Promise.all(releasePromises);
+
+		// Display results
+		for (const result of results) {
+			if (result.error) {
+				console.log(`\n${pc.bold(pc.cyan(result.kitConfig.name))} - ${pc.red("Error")}`);
+				console.log(pc.dim(`  ${result.error}`));
+			} else {
+				displayKitReleases(result.kitConfig.name, result.releases);
+			}
+		}
+
+		prompts.outro("✨ Done");
+	} catch (error) {
+		logger.error(error instanceof Error ? error.message : "Unknown error occurred");
+		process.exit(1);
+	}
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { cac } from "cac";
 import { newCommand } from "./commands/new.js";
 import { updateCommand } from "./commands/update.js";
+import { versionCommand } from "./commands/version.js";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 
@@ -34,6 +35,16 @@ cli
 		await updateCommand(options);
 	});
 
+// Versions command
+cli
+	.command("versions", "List available versions of ClaudeKit repositories")
+	.option("--kit <kit>", "Filter by specific kit (engineer, marketing)")
+	.option("--limit <limit>", "Number of releases to show (default: 30)")
+	.option("--all", "Show all releases including prereleases")
+	.action(async (options) => {
+		await versionCommand(options);
+	});
+
 // Version
 cli.version(packageJson.version);
 

package/src/types.ts

@@ -19,6 +19,13 @@ export const UpdateCommandOptionsSchema = z.object({
 });
 export type UpdateCommandOptions = z.infer<typeof UpdateCommandOptionsSchema>;
 
+export const VersionCommandOptionsSchema = z.object({
+	kit: KitType.optional(),
+	limit: z.number().optional(),
+	all: z.boolean().optional(),
+});
+export type VersionCommandOptions = z.infer<typeof VersionCommandOptionsSchema>;
+
 // Config schemas
 export const ConfigSchema = z.object({
 	github: z