claudekit-cli 1.0.1 → 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,15 @@
+# [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)
 
 

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

@@ -94,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
 
@@ -233,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/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.1",
+	"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

package/tests/commands/version.test.ts

@@ -0,0 +1,297 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import type { GitHubRelease } from "../../src/types.js";
+import { AVAILABLE_KITS, VersionCommandOptionsSchema } from "../../src/types.js";
+
+describe("Version Command", () => {
+	beforeEach(() => {
+		// Set environment variable to avoid auth prompts during tests
+		process.env.GITHUB_TOKEN = "ghp_test_token_for_testing";
+	});
+
+	describe("VersionCommandOptionsSchema", () => {
+		test("should accept valid options with kit filter", () => {
+			const options = { kit: "engineer" as const };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.kit).toBe("engineer");
+		});
+
+		test("should accept valid options with limit", () => {
+			const options = { limit: 10 };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.limit).toBe(10);
+		});
+
+		test("should accept valid options with all flag", () => {
+			const options = { all: true };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.all).toBe(true);
+		});
+
+		test("should accept all options combined", () => {
+			const options = { kit: "marketing" as const, limit: 20, all: true };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.kit).toBe("marketing");
+			expect(result.limit).toBe(20);
+			expect(result.all).toBe(true);
+		});
+
+		test("should accept empty options", () => {
+			const options = {};
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.kit).toBeUndefined();
+			expect(result.limit).toBeUndefined();
+			expect(result.all).toBeUndefined();
+		});
+
+		test("should reject invalid kit type", () => {
+			const options = { kit: "invalid" };
+			expect(() => VersionCommandOptionsSchema.parse(options)).toThrow();
+		});
+	});
+
+	describe("Kit Configuration", () => {
+		test("should have engineer kit configured", () => {
+			const engineerKit = AVAILABLE_KITS.engineer;
+			expect(engineerKit.name).toBe("ClaudeKit Engineer");
+			expect(engineerKit.repo).toBe("claudekit-engineer");
+			expect(engineerKit.owner).toBe("mrgoonie");
+		});
+
+		test("should have marketing kit configured", () => {
+			const marketingKit = AVAILABLE_KITS.marketing;
+			expect(marketingKit.name).toBe("ClaudeKit Marketing");
+			expect(marketingKit.repo).toBe("claudekit-marketing");
+			expect(marketingKit.owner).toBe("mrgoonie");
+		});
+	});
+
+	describe("Release Data Handling", () => {
+		test("should handle release with all fields", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0",
+				name: "Release 1.0.0",
+				draft: false,
+				prerelease: false,
+				assets: [],
+				published_at: "2024-01-01T00:00:00Z",
+			};
+
+			expect(release.tag_name).toBe("v1.0.0");
+			expect(release.name).toBe("Release 1.0.0");
+			expect(release.draft).toBe(false);
+			expect(release.prerelease).toBe(false);
+		});
+
+		test("should handle release without published_at", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0",
+				name: "Release 1.0.0",
+				draft: false,
+				prerelease: false,
+				assets: [],
+			};
+
+			expect(release.published_at).toBeUndefined();
+		});
+
+		test("should handle draft release", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0-draft",
+				name: "Draft Release",
+				draft: true,
+				prerelease: false,
+				assets: [],
+			};
+
+			expect(release.draft).toBe(true);
+		});
+
+		test("should handle prerelease", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0-beta.1",
+				name: "Beta Release",
+				draft: false,
+				prerelease: true,
+				assets: [],
+			};
+
+			expect(release.prerelease).toBe(true);
+		});
+	});
+
+	describe("Date Formatting", () => {
+		test("should format recent dates correctly", () => {
+			const now = new Date();
+			const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+			const dateString = yesterday.toISOString();
+
+			// The actual formatting logic is in the command file
+			// We just verify the date string is valid
+			expect(dateString).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+		});
+
+		test("should handle undefined date", () => {
+			const dateString = undefined;
+			expect(dateString).toBeUndefined();
+		});
+	});
+
+	describe("Release Filtering", () => {
+		const releases: GitHubRelease[] = [
+			{
+				id: 1,
+				tag_name: "v1.0.0",
+				name: "Stable Release",
+				draft: false,
+				prerelease: false,
+				assets: [],
+				published_at: "2024-01-01T00:00:00Z",
+			},
+			{
+				id: 2,
+				tag_name: "v1.1.0-beta.1",
+				name: "Beta Release",
+				draft: false,
+				prerelease: true,
+				assets: [],
+				published_at: "2024-01-02T00:00:00Z",
+			},
+			{
+				id: 3,
+				tag_name: "v1.2.0-draft",
+				name: "Draft Release",
+				draft: true,
+				prerelease: false,
+				assets: [],
+				published_at: "2024-01-03T00:00:00Z",
+			},
+		];
+
+		test("should filter out drafts by default", () => {
+			const stable = releases.filter((r) => !r.draft && !r.prerelease);
+			expect(stable).toHaveLength(1);
+			expect(stable[0].tag_name).toBe("v1.0.0");
+		});
+
+		test("should filter out prereleases by default", () => {
+			const stable = releases.filter((r) => !r.draft && !r.prerelease);
+			expect(stable.every((r) => !r.prerelease)).toBe(true);
+		});
+
+		test("should include all when --all flag is used", () => {
+			const all = releases; // No filtering when --all is true
+			expect(all).toHaveLength(3);
+		});
+
+		test("should handle empty release list", () => {
+			const empty: GitHubRelease[] = [];
+			expect(empty).toHaveLength(0);
+		});
+	});
+
+	describe("Command Options Validation", () => {
+		test("should validate limit as number", () => {
+			const validLimit = { limit: 50 };
+			const result = VersionCommandOptionsSchema.parse(validLimit);
+			expect(result.limit).toBe(50);
+		});
+
+		test("should validate all as boolean", () => {
+			const validAll = { all: false };
+			const result = VersionCommandOptionsSchema.parse(validAll);
+			expect(result.all).toBe(false);
+		});
+
+		test("should handle optional fields", () => {
+			const minimal = {};
+			const result = VersionCommandOptionsSchema.parse(minimal);
+			expect(result).toBeDefined();
+		});
+	});
+
+	describe("Error Scenarios", () => {
+		test("should handle invalid option types", () => {
+			const invalidLimit = { limit: "not-a-number" };
+			expect(() => VersionCommandOptionsSchema.parse(invalidLimit)).toThrow();
+		});
+
+		test("should handle invalid all flag type", () => {
+			const invalidAll = { all: "not-a-boolean" };
+			expect(() => VersionCommandOptionsSchema.parse(invalidAll)).toThrow();
+		});
+	});
+
+	describe("Assets Handling", () => {
+		test("should handle release with multiple assets", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0",
+				name: "Release",
+				draft: false,
+				prerelease: false,
+				assets: [
+					{
+						id: 1,
+						name: "package.tar.gz",
+						browser_download_url: "https://example.com/package.tar.gz",
+						size: 1024,
+						content_type: "application/gzip",
+					},
+					{
+						id: 2,
+						name: "package.zip",
+						browser_download_url: "https://example.com/package.zip",
+						size: 2048,
+						content_type: "application/zip",
+					},
+				],
+			};
+
+			expect(release.assets).toHaveLength(2);
+		});
+
+		test("should handle release with no assets", () => {
+			const release: GitHubRelease = {
+				id: 1,
+				tag_name: "v1.0.0",
+				name: "Release",
+				draft: false,
+				prerelease: false,
+				assets: [],
+			};
+
+			expect(release.assets).toHaveLength(0);
+		});
+	});
+
+	describe("Integration Scenarios", () => {
+		test("should handle both kits in parallel", () => {
+			const kits = Object.keys(AVAILABLE_KITS);
+			expect(kits).toContain("engineer");
+			expect(kits).toContain("marketing");
+			expect(kits).toHaveLength(2);
+		});
+
+		test("should support filtering by engineer kit", () => {
+			const options = { kit: "engineer" as const };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.kit).toBe("engineer");
+
+			const kitConfig = AVAILABLE_KITS[result.kit];
+			expect(kitConfig.repo).toBe("claudekit-engineer");
+		});
+
+		test("should support filtering by marketing kit", () => {
+			const options = { kit: "marketing" as const };
+			const result = VersionCommandOptionsSchema.parse(options);
+			expect(result.kit).toBe("marketing");
+
+			const kitConfig = AVAILABLE_KITS[result.kit];
+			expect(kitConfig.repo).toBe("claudekit-marketing");
+		});
+	});
+});