ocx 0.1.1 → 1.0.0

package/src/schemas/registry.ts

@@ -1,268 +0,0 @@
-/**
- * Registry & Component Schemas
- *
- * Zod schemas with fail-fast validation following the 5 Laws of Elegant Defense.
- * All validation errors include clear messages with examples of valid input.
- */
-
-import { z } from "zod"
-
-// =============================================================================
-// OPENCODE NAMING CONSTRAINTS (from OpenCode docs)
-// =============================================================================
-
-/**
- * OpenCode name schema following official constraints:
- * - 1-64 characters
- * - Lowercase alphanumeric with single hyphen separators
- * - Cannot start or end with hyphen
- * - Cannot contain consecutive hyphens
- *
- * Regex: ^[a-z0-9]+(-[a-z0-9]+)*$
- */
-export const openCodeNameSchema = z
-	.string()
-	.min(1, "Name cannot be empty")
-	.max(64, "Name cannot exceed 64 characters")
-	.regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, {
-		message:
-			"Must be lowercase alphanumeric with single hyphen separators (e.g., 'my-component', 'kdco-plan'). Cannot start/end with hyphen or have consecutive hyphens.",
-	})
-
-/**
- * Creates a component name schema that enforces registry prefix.
- * All components in a registry must start with the registry's prefix.
- */
-export const createComponentNameSchema = (prefix: string) =>
-	openCodeNameSchema.refine((name) => name.startsWith(`${prefix}-`), {
-		message: `Component name must start with registry prefix "${prefix}-" (e.g., "${prefix}-my-component")`,
-	})
-
-// =============================================================================
-// FILE TARGET SCHEMAS
-// =============================================================================
-
-/**
- * Valid component types and their target directories
- */
-export const COMPONENT_TYPE_DIRS = {
-	"ocx:agent": "agent",
-	"ocx:skill": "skill",
-	"ocx:plugin": "plugin",
-	"ocx:command": "command",
-	"ocx:tool": "tool",
-	"ocx:bundle": null, // Bundles don't have a target directory
-} as const
-
-export const componentTypeSchema = z.enum([
-	"ocx:agent",
-	"ocx:skill",
-	"ocx:plugin",
-	"ocx:command",
-	"ocx:tool",
-	"ocx:bundle",
-])
-
-export type ComponentType = z.infer<typeof componentTypeSchema>
-
-/**
- * Target path must be inside .opencode/ with valid subdirectory
- */
-export const targetPathSchema = z
-	.string()
-	.refine((path) => path.startsWith(".opencode/"), {
-		message: 'Target path must start with ".opencode/"',
-	})
-	.refine(
-		(path) => {
-			const parts = path.split("/")
-			if (parts.length < 2) return false
-			const dir = parts[1]
-			return ["agent", "skill", "plugin", "command", "tool", "philosophy"].includes(dir)
-		},
-		{
-			message:
-				'Target must be in a valid directory: ".opencode/{agent|skill|plugin|command|tool|philosophy}/..."',
-		},
-	)
-
-/**
- * Skill-specific target validation.
- * Skills must be in: .opencode/skill/<name>/SKILL.md
- */
-export const skillTargetSchema = z
-	.string()
-	.regex(/^\.opencode\/skill\/[a-z0-9]+(-[a-z0-9]+)*\/SKILL\.md$/, {
-		message:
-			'Skill target must match pattern ".opencode/skill/<name>/SKILL.md" where name follows OpenCode naming rules',
-	})
-
-// =============================================================================
-// MCP SERVER SCHEMA
-// =============================================================================
-
-export const mcpServerSchema = z
-	.object({
-		type: z.enum(["remote", "local"]),
-		url: z.string().url().optional(),
-		command: z.array(z.string()).optional(),
-		headers: z.record(z.string()).optional(),
-		enabled: z.boolean().default(true),
-	})
-	.refine(
-		(data) => {
-			if (data.type === "remote" && !data.url) {
-				return false
-			}
-			if (data.type === "local" && !data.command) {
-				return false
-			}
-			return true
-		},
-		{
-			message: "Remote MCP servers require 'url', local servers require 'command'",
-		},
-	)
-
-export type McpServer = z.infer<typeof mcpServerSchema>
-
-// =============================================================================
-// COMPONENT FILE SCHEMA
-// =============================================================================
-
-export const componentFileSchema = z.object({
-	/** Source path in registry */
-	path: z.string().min(1, "File path cannot be empty"),
-	/** Target path in .opencode/ */
-	target: targetPathSchema,
-})
-
-export type ComponentFile = z.infer<typeof componentFileSchema>
-
-// =============================================================================
-// COMPONENT MANIFEST SCHEMA
-// =============================================================================
-
-export const componentManifestSchema = z.object({
-	/** Component name (must include registry prefix) */
-	name: openCodeNameSchema,
-
-	/** Component type */
-	type: componentTypeSchema,
-
-	/** Human-readable description */
-	description: z.string().min(1).max(1024),
-
-	/** Files to install */
-	files: z.array(componentFileSchema),
-
-	/** Dependencies on other components */
-	dependencies: z.array(openCodeNameSchema).default([]),
-
-	/** MCP servers this component needs */
-	mcpServers: z.record(mcpServerSchema).optional(),
-
-	/** Scope MCP servers to this agent only? Default: "agent" */
-	mcpScope: z.enum(["agent", "global"]).default("agent"),
-})
-
-export type ComponentManifest = z.infer<typeof componentManifestSchema>
-
-// =============================================================================
-// REGISTRY SCHEMA
-// =============================================================================
-
-/**
- * Semver regex for version validation
- */
-const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/
-
-export const registrySchema = z
-	.object({
-		/** Registry name */
-		name: z.string().min(1, "Registry name cannot be empty"),
-
-		/** Registry prefix - REQUIRED, all components must use this */
-		prefix: openCodeNameSchema,
-
-		/** Registry version (semver) */
-		version: z.string().regex(semverRegex, {
-			message: "Version must be valid semver (e.g., '1.0.0', '2.1.0-beta.1')",
-		}),
-
-		/** Registry author */
-		author: z.string().min(1, "Author cannot be empty"),
-
-		/** Components in this registry */
-		components: z.array(componentManifestSchema),
-	})
-	.refine(
-		(data) => {
-			// All component names must start with the registry prefix
-			return data.components.every((c) => c.name.startsWith(`${data.prefix}-`))
-		},
-		{
-			message: "All component names must start with the registry prefix",
-		},
-	)
-	.refine(
-		(data) => {
-			// All dependencies must exist within the registry
-			const componentNames = new Set(data.components.map((c) => c.name))
-			for (const component of data.components) {
-				for (const dep of component.dependencies) {
-					if (!componentNames.has(dep)) {
-						return false
-					}
-				}
-			}
-			return true
-		},
-		{
-			message: "All dependencies must reference components that exist in the registry",
-		},
-	)
-
-export type Registry = z.infer<typeof registrySchema>
-
-// =============================================================================
-// PACKUMENT SCHEMA (npm-style versioned component)
-// =============================================================================
-
-export const packumentSchema = z.object({
-	/** Component name */
-	name: openCodeNameSchema,
-
-	/** Latest version */
-	"dist-tags": z.object({
-		latest: z.string(),
-	}),
-
-	/** All versions */
-	versions: z.record(componentManifestSchema),
-})
-
-export type Packument = z.infer<typeof packumentSchema>
-
-// =============================================================================
-// REGISTRY INDEX SCHEMA
-// =============================================================================
-
-export const registryIndexSchema = z.object({
-	/** Registry metadata */
-	name: z.string(),
-	prefix: openCodeNameSchema,
-	version: z.string(),
-	author: z.string(),
-
-	/** Component summaries for search */
-	components: z.array(
-		z.object({
-			name: openCodeNameSchema,
-			type: componentTypeSchema,
-			description: z.string(),
-		}),
-	),
-})
-
-export type RegistryIndex = z.infer<typeof registryIndexSchema>

package/src/utils/env.ts

@@ -1,27 +0,0 @@
-/**
- * Environment detection utilities
- * Detects CI, TTY, color support for proper output handling
- */
-
-/** Running in CI environment */
-export const isCI = Boolean(
-	process.env.CI ||
-		process.env.GITHUB_ACTIONS ||
-		process.env.GITLAB_CI ||
-		process.env.CIRCLECI ||
-		process.env.JENKINS_URL ||
-		process.env.BUILDKITE,
-)
-
-/** Running in interactive terminal */
-export const isTTY = Boolean(process.stdout.isTTY && !isCI)
-
-/** Terminal supports colors */
-export const supportsColor = Boolean(
-	isTTY && process.env.FORCE_COLOR !== "0" && process.env.NO_COLOR === undefined,
-)
-
-/** Get terminal width, default to 80 */
-export function getTerminalWidth(): number {
-	return process.stdout.columns || 80
-}

package/src/utils/errors.ts

@@ -1,81 +0,0 @@
-/**
- * Custom error classes with error codes
- * Following fail-fast philosophy - clear, actionable errors
- */
-
-export type ErrorCode =
-	| "NOT_FOUND"
-	| "NETWORK_ERROR"
-	| "CONFIG_ERROR"
-	| "VALIDATION_ERROR"
-	| "CONFLICT"
-	| "PERMISSION_ERROR"
-	| "INTEGRITY_ERROR"
-
-export const EXIT_CODES = {
-	SUCCESS: 0,
-	GENERAL: 1,
-	NOT_FOUND: 66,
-	NETWORK: 69,
-	CONFIG: 78,
-	INTEGRITY: 1, // Exit code for integrity failures
-} as const
-
-export class OCXError extends Error {
-	constructor(
-		message: string,
-		public readonly code: ErrorCode,
-		public readonly exitCode: number = EXIT_CODES.GENERAL,
-	) {
-		super(message)
-		this.name = "OCXError"
-	}
-}
-
-export class NotFoundError extends OCXError {
-	constructor(message: string) {
-		super(message, "NOT_FOUND", EXIT_CODES.NOT_FOUND)
-		this.name = "NotFoundError"
-	}
-}
-
-export class NetworkError extends OCXError {
-	constructor(message: string) {
-		super(message, "NETWORK_ERROR", EXIT_CODES.NETWORK)
-		this.name = "NetworkError"
-	}
-}
-
-export class ConfigError extends OCXError {
-	constructor(message: string) {
-		super(message, "CONFIG_ERROR", EXIT_CODES.CONFIG)
-		this.name = "ConfigError"
-	}
-}
-
-export class ValidationError extends OCXError {
-	constructor(message: string) {
-		super(message, "VALIDATION_ERROR", EXIT_CODES.GENERAL)
-		this.name = "ValidationError"
-	}
-}
-
-export class ConflictError extends OCXError {
-	constructor(message: string) {
-		super(message, "CONFLICT", EXIT_CODES.GENERAL)
-		this.name = "ConflictError"
-	}
-}
-
-export class IntegrityError extends OCXError {
-	constructor(component: string, expected: string, found: string) {
-		const message =
-			`Integrity verification failed for "${component}"\n` +
-			`  Expected: ${expected}\n` +
-			`  Found:    ${found}\n\n` +
-			`The registry content has changed since this component was locked.\n` +
-			`This could indicate tampering or an unauthorized update.`
-		super(message, "INTEGRITY_ERROR", EXIT_CODES.INTEGRITY)
-		this.name = "IntegrityError"
-	}
-}

package/src/utils/handle-error.ts

@@ -1,108 +0,0 @@
-/**
- * Error handler for CLI commands
- * Converts errors to user-friendly output with proper exit codes
- */
-
-import { ZodError } from "zod"
-
-import { OCXError, EXIT_CODES } from "./errors"
-import { logger } from "./logger"
-
-export interface HandleErrorOptions {
-	json?: boolean
-}
-
-/**
- * Handle errors consistently across all commands
- * Fail-fast: exit immediately with appropriate code
- */
-export function handleError(error: unknown, options: HandleErrorOptions = {}): never {
-	// JSON mode: structured output
-	if (options.json) {
-		const output = formatErrorAsJson(error)
-		console.log(JSON.stringify(output, null, 2))
-		process.exit(output.exitCode)
-	}
-
-	// OCX errors: known errors with codes
-	if (error instanceof OCXError) {
-		logger.error(error.message)
-		process.exit(error.exitCode)
-	}
-
-	// Zod validation errors: format nicely
-	if (error instanceof ZodError) {
-		logger.error("Validation failed:")
-		for (const issue of error.issues) {
-			const path = issue.path.join(".")
-			logger.error(`  ${path}: ${issue.message}`)
-		}
-		process.exit(EXIT_CODES.CONFIG)
-	}
-
-	// Unknown errors
-	if (error instanceof Error) {
-		logger.error(error.message)
-		if (process.env.DEBUG) {
-			console.error(error.stack)
-		}
-	} else {
-		logger.error("An unknown error occurred")
-	}
-
-	process.exit(EXIT_CODES.GENERAL)
-}
-
-interface JsonErrorOutput {
-	success: false
-	error: {
-		code: string
-		message: string
-	}
-	exitCode: number
-	meta: {
-		timestamp: string
-	}
-}
-
-function formatErrorAsJson(error: unknown): JsonErrorOutput {
-	if (error instanceof OCXError) {
-		return {
-			success: false,
-			error: {
-				code: error.code,
-				message: error.message,
-			},
-			exitCode: error.exitCode,
-			meta: {
-				timestamp: new Date().toISOString(),
-			},
-		}
-	}
-
-	if (error instanceof ZodError) {
-		return {
-			success: false,
-			error: {
-				code: "VALIDATION_ERROR",
-				message: error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
-			},
-			exitCode: EXIT_CODES.CONFIG,
-			meta: {
-				timestamp: new Date().toISOString(),
-			},
-		}
-	}
-
-	return {
-		success: false,
-		error: {
-			code: "UNKNOWN_ERROR",
-			message: error instanceof Error ? error.message : "An unknown error occurred",
-		},
-		exitCode: EXIT_CODES.GENERAL,
-		meta: {
-			timestamp: new Date().toISOString(),
-		},
-	}
-}

package/src/utils/index.ts

@@ -1,10 +0,0 @@
-/**
- * Core utilities for OCX CLI
- */
-
-export * from "./env.js"
-export * from "./errors.js"
-export * from "./logger.js"
-export * from "./spinner.js"
-export * from "./handle-error.js"
-export * from "./json-output.js"

package/src/utils/json-output.ts

@@ -1,107 +0,0 @@
-/**
- * JSON output utilities for CI/CD integration
- * Following GitHub CLI patterns for consistent --json flag handling
- */
-
-import { type ErrorCode, EXIT_CODES, OCXError } from "./errors.js"
-
-// JSON response envelope
-export interface JsonResponse<T = unknown> {
-	success: boolean
-	data?: T
-	error?: {
-		code: ErrorCode
-		message: string
-	}
-	meta?: {
-		timestamp: string
-		version: string
-	}
-}
-
-// Global JSON mode state
-let jsonMode = false
-
-export function setJsonMode(enabled: boolean): void {
-	jsonMode = enabled
-}
-
-export function isJsonMode(): boolean {
-	return jsonMode
-}
-
-/**
- * Output data as JSON
- */
-export function outputJson(data: any): void {
-	console.log(JSON.stringify(data, null, 2))
-}
-
-/**
- * Output success response
- */
-export function outputSuccess<T>(data: T): void {
-	const response: JsonResponse<T> = {
-		success: true,
-		data,
-		meta: {
-			timestamp: new Date().toISOString(),
-			version: "0.1.0",
-		},
-	}
-	outputJson(response)
-}
-
-/**
- * Output error response
- */
-export function outputError(code: ErrorCode, message: string): void {
-	const response: JsonResponse = {
-		success: false,
-		error: { code, message },
-		meta: {
-			timestamp: new Date().toISOString(),
-			version: "0.1.0",
-		},
-	}
-	outputJson(response)
-}
-
-/**
- * Get exit code for error code
- */
-export function getExitCode(code: ErrorCode): number {
-	switch (code) {
-		case "NOT_FOUND":
-			return EXIT_CODES.NOT_FOUND
-		case "NETWORK_ERROR":
-			return EXIT_CODES.NETWORK
-		case "CONFIG_ERROR":
-		case "VALIDATION_ERROR":
-			return EXIT_CODES.CONFIG
-		default:
-			return EXIT_CODES.GENERAL
-	}
-}
-
-/**
- * Wrap a command handler to support JSON output mode
- */
-export function withJsonOutput<T extends (...args: unknown[]) => Promise<void>>(handler: T): T {
-	return (async (...args: unknown[]) => {
-		try {
-			await handler(...args)
-		} catch (error) {
-			if (isJsonMode()) {
-				if (error instanceof OCXError) {
-					outputError(error.code, error.message)
-					process.exit(error.exitCode)
-				}
-				const message = error instanceof Error ? error.message : String(error)
-				outputError("VALIDATION_ERROR", message)
-				process.exit(EXIT_CODES.GENERAL)
-			}
-			throw error
-		}
-	}) as T
-}

package/src/utils/logger.ts

@@ -1,72 +0,0 @@
-/**
- * Logger utility with quiet/verbose modes
- * Inspired by ShadCN's logger pattern
- */
-
-import kleur from "kleur"
-import { supportsColor } from "./env"
-
-// Disable colors if not supported
-if (!supportsColor) {
-	kleur.enabled = false
-}
-
-export interface LoggerOptions {
-	quiet?: boolean
-	verbose?: boolean
-}
-
-let options: LoggerOptions = {}
-
-export function setLoggerOptions(opts: LoggerOptions): void {
-	options = opts
-}
-
-export const logger = {
-	info(...args: unknown[]): void {
-		if (options.quiet) return
-		console.log(kleur.blue("info"), ...args)
-	},
-
-	success(...args: unknown[]): void {
-		if (options.quiet) return
-		console.log(kleur.green("✓"), ...args)
-	},
-
-	warn(...args: unknown[]): void {
-		if (options.quiet) return
-		console.warn(kleur.yellow("warn"), ...args)
-	},
-
-	error(...args: unknown[]): void {
-		// Errors are always shown
-		console.error(kleur.red("error"), ...args)
-	},
-
-	debug(...args: unknown[]): void {
-		if (!options.verbose) return
-		console.log(kleur.gray("debug"), ...args)
-	},
-
-	log(...args: unknown[]): void {
-		if (options.quiet) return
-		console.log(...args)
-	},
-
-	/** Print a blank line */
-	break(): void {
-		if (options.quiet) return
-		console.log("")
-	},
-}
-
-/** Highlight text with color */
-export const highlight = {
-	component: (text: string) => kleur.cyan(text),
-	path: (text: string) => kleur.green(text),
-	command: (text: string) => kleur.yellow(text),
-	url: (text: string) => kleur.blue().underline(text),
-	error: (text: string) => kleur.red(text),
-	dim: (text: string) => kleur.gray(text),
-	bold: (text: string) => kleur.bold(text),
-}