refactor(cli): extract and unify types in cli (ts/py)

William Bakst · William Bakst · commit 0048df1154c4 · 2026-02-03T15:59:09.000-08:00
diff --git a/python/mirascope/cli/registry/__init__.py b/python/mirascope/cli/registry/__init__.py
@@ -1,5 +1,23 @@
-"""Registry client for fetching items from the Mirascope registry."""
+"""Registry client and types for the Mirascope registry."""
 
 from mirascope.cli.registry.client import RegistryClient
+from mirascope.cli.registry.schemas import (
+    MirascopeConfig,
+    RegistryDependencies,
+    RegistryFile,
+    RegistryIndex,
+    RegistryIndexItem,
+    RegistryItem,
+    RegistryVersionConstraint,
+)
 
-__all__ = ["RegistryClient"]
+__all__ = [
+    "MirascopeConfig",
+    "RegistryClient",
+    "RegistryDependencies",
+    "RegistryFile",
+    "RegistryIndex",
+    "RegistryIndexItem",
+    "RegistryItem",
+    "RegistryVersionConstraint",
+]
diff --git a/python/mirascope/cli/registry/schemas.py b/python/mirascope/cli/registry/schemas.py
@@ -1,49 +1,68 @@
-"""Pydantic schemas for registry items."""
+"""Pydantic schemas for registry items and configuration."""
 
 from __future__ import annotations
 
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 
 
 class RegistryFile(BaseModel):
-    """A file in a registry item."""
+    """A file within a registry item."""
 
     path: str
+    """Source path within the registry item."""
     target: str
+    """Target path where the file will be written."""
     content: str = ""
+    """File content (populated in built registry items)."""
     type: str = ""
+    """Optional file type annotation."""
 
 
 class RegistryDependencies(BaseModel):
-    """Dependencies for a registry item."""
+    """Dependencies required by a registry item."""
 
     pip: list[str] = []
+    """Python pip packages."""
     npm: list[str] = []
+    """npm packages."""
 
 
 class RegistryVersionConstraint(BaseModel):
-    """Version constraints for a registry item."""
+    """Version constraints for Mirascope compatibility."""
 
     minVersion: str | None = None
+    """Minimum compatible version."""
     maxVersion: str | None = None
+    """Maximum compatible version."""
 
 
 class RegistryItem(BaseModel):
-    """A registry item."""
+    """A registry item (tool, agent, prompt, or integration)."""
 
     name: str
+    """Unique item name."""
     type: str
+    """Item type (e.g., 'registry:tool', 'registry:agent')."""
     title: str = ""
+    """Human-readable title."""
     description: str = ""
+    """Description of the item."""
     version: str = "1.0.0"
+    """Item version."""
     language: str = ""
+    """Language this item is for (python or typescript)."""
     categories: list[str] = []
+    """Categories for filtering/searching."""
     mirascope: dict[str, RegistryVersionConstraint] = {}
+    """Mirascope version constraints by language."""
     files: list[RegistryFile] = []
+    """Files included in this item."""
     dependencies: RegistryDependencies = RegistryDependencies()
+    """External dependencies."""
     registryDependencies: list[str] = []
+    """Other registry items this depends on."""
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> RegistryItem:
@@ -52,23 +71,46 @@ def from_dict(cls, data: dict[str, Any]) -> RegistryItem:
 
 
 class RegistryIndexItem(BaseModel):
-    """An item in the registry index."""
+    """An item entry in the registry index."""
 
     name: str
+    """Item name."""
     type: str
+    """Item type."""
     path: str
+    """Path within the registry."""
     description: str = ""
+    """Optional description."""
 
 
 class RegistryIndex(BaseModel):
-    """The registry index."""
+    """The registry index containing all available items."""
 
     name: str
+    """Registry name."""
     version: str
+    """Registry version."""
     homepage: str = ""
+    """Registry homepage URL."""
     items: list[RegistryIndexItem] = []
+    """All items in the registry."""
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> RegistryIndex:
         """Create a RegistryIndex from a dictionary."""
         return cls.model_validate(data)
+
+
+class MirascopeConfig(BaseModel):
+    """Mirascope project configuration (mirascope.json)."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    schema_: str | None = None
+    """JSON schema URL."""
+    language: str = "python"
+    """Project language (python or typescript)."""
+    registry: str = "https://mirascope.com/registry"
+    """Registry URL."""
+    paths: dict[str, str] = {}
+    """Path mappings for item types."""
diff --git a/typescript/src/cli/commands/add.ts b/typescript/src/cli/commands/add.ts
@@ -3,9 +3,10 @@
  */
 
 import { join } from 'path';
-import { RegistryClient } from '../registry/client';
-import { loadConfig } from '../utils/config';
-import { writeFile } from '../utils/file-ops';
+import { RegistryClient } from '@/cli/registry/client';
+import type { RegistryItem } from '@/cli/registry/types';
+import { loadConfig } from '@/cli/utils/config';
+import { writeFile } from '@/cli/utils/file-ops';
 
 interface AddOptions {
   items: string[];
@@ -14,22 +15,6 @@ interface AddOptions {
   registryUrl: string;
 }
 
-interface RegistryFile {
-  path: string;
-  target: string;
-  content: string;
-}
-
-interface RegistryItem {
-  name: string;
-  type: string;
-  files: RegistryFile[];
-  dependencies: {
-    pip: string[];
-    npm: string[];
-  };
-}
-
 async function loadLocalItem(itemPath: string): Promise<RegistryItem | null> {
   try {
     // eslint-disable-next-line no-undef
diff --git a/typescript/src/cli/commands/init.ts b/typescript/src/cli/commands/init.ts
@@ -3,18 +3,7 @@
  */
 
 import { join } from 'path';
-
-interface MirascopeConfig {
-  $schema: string;
-  language: string;
-  registry: string;
-  paths: {
-    tools: string;
-    agents: string;
-    prompts: string;
-    integrations: string;
-  };
-}
+import type { MirascopeConfig } from '@/cli/registry/types';
 
 export async function runInit(): Promise<number> {
   const configPath = join(process.cwd(), 'mirascope.json');
diff --git a/typescript/src/cli/commands/list.ts b/typescript/src/cli/commands/list.ts
@@ -2,23 +2,14 @@
  * List command - List available registry items.
  */
 
-import { RegistryClient } from '../registry/client';
+import { RegistryClient } from '@/cli/registry/client';
+import type { RegistryIndex, RegistryIndexItem } from '@/cli/registry/types';
 
 interface ListOptions {
   itemType?: string;
   registryUrl: string;
 }
 
-interface RegistryIndexItem {
-  name: string;
-  type: string;
-  description?: string;
-}
-
-interface RegistryIndex {
-  items: RegistryIndexItem[];
-}
-
 export async function runList(options: ListOptions): Promise<number> {
   const { itemType, registryUrl } = options;
 
diff --git a/typescript/src/cli/index.ts b/typescript/src/cli/index.ts
@@ -4,9 +4,9 @@
  */
 
 import { parseArgs } from 'util';
-import { runAdd } from './commands/add';
-import { runInit } from './commands/init';
-import { runList } from './commands/list';
+import { runAdd } from '@/cli/commands/add';
+import { runInit } from '@/cli/commands/init';
+import { runList } from '@/cli/commands/list';
 
 const VERSION = '0.1.0';
 const DEFAULT_REGISTRY = 'https://mirascope.com/registry';
diff --git a/typescript/src/cli/registry/client.ts b/typescript/src/cli/registry/client.ts
@@ -2,31 +2,7 @@
  * HTTP client for the Mirascope registry.
  */
 
-interface RegistryItem {
-  name: string;
-  type: string;
-  files: Array<{
-    path: string;
-    target: string;
-    content: string;
-  }>;
-  dependencies: {
-    pip: string[];
-    npm: string[];
-  };
-}
-
-interface RegistryIndex {
-  name: string;
-  version: string;
-  homepage: string;
-  items: Array<{
-    name: string;
-    type: string;
-    path: string;
-    description?: string;
-  }>;
-}
+import type { RegistryIndex, RegistryItem } from '@/cli/registry/types';
 
 export class RegistryClient {
   private baseUrl: string;
diff --git a/typescript/src/cli/registry/index.ts b/typescript/src/cli/registry/index.ts
@@ -0,0 +1,14 @@
+/**
+ * Registry module exports.
+ */
+
+export { RegistryClient } from '@/cli/registry/client';
+export type {
+  MirascopeConfig,
+  RegistryDependencies,
+  RegistryFile,
+  RegistryIndex,
+  RegistryIndexItem,
+  RegistryItem,
+  RegistryVersionConstraint,
+} from '@/cli/registry/types';
diff --git a/typescript/src/cli/registry/types.ts b/typescript/src/cli/registry/types.ts
@@ -0,0 +1,93 @@
+/**
+ * Shared types for the Mirascope CLI and registry.
+ */
+
+/** A file within a registry item. */
+export interface RegistryFile {
+  /** Source path within the registry item. */
+  path: string;
+  /** Target path where the file will be written. */
+  target: string;
+  /** File content (populated in built registry items). */
+  content: string;
+  /** Optional file type annotation. */
+  type?: string;
+}
+
+/** Dependencies required by a registry item. */
+export interface RegistryDependencies {
+  /** Python pip packages. */
+  pip: string[];
+  /** npm packages. */
+  npm: string[];
+}
+
+/** Version constraints for Mirascope compatibility. */
+export interface RegistryVersionConstraint {
+  /** Minimum compatible version. */
+  minVersion?: string;
+  /** Maximum compatible version. */
+  maxVersion?: string;
+}
+
+/** A registry item (tool, agent, prompt, or integration). */
+export interface RegistryItem {
+  /** Unique item name. */
+  name: string;
+  /** Item type (e.g., "registry:tool", "registry:agent"). */
+  type: string;
+  /** Human-readable title. */
+  title?: string;
+  /** Description of the item. */
+  description?: string;
+  /** Item version. */
+  version?: string;
+  /** Language this item is for (python or typescript). */
+  language?: string;
+  /** Categories for filtering/searching. */
+  categories?: string[];
+  /** Mirascope version constraints by language. */
+  mirascope?: Record<string, RegistryVersionConstraint>;
+  /** Files included in this item. */
+  files: RegistryFile[];
+  /** External dependencies. */
+  dependencies: RegistryDependencies;
+  /** Other registry items this depends on. */
+  registryDependencies?: string[];
+}
+
+/** An item entry in the registry index. */
+export interface RegistryIndexItem {
+  /** Item name. */
+  name: string;
+  /** Item type. */
+  type: string;
+  /** Path within the registry. */
+  path: string;
+  /** Optional description. */
+  description?: string;
+}
+
+/** The registry index containing all available items. */
+export interface RegistryIndex {
+  /** Registry name. */
+  name: string;
+  /** Registry version. */
+  version: string;
+  /** Registry homepage URL. */
+  homepage?: string;
+  /** All items in the registry. */
+  items: RegistryIndexItem[];
+}
+
+/** Mirascope project configuration (mirascope.json). */
+export interface MirascopeConfig {
+  /** JSON schema URL. */
+  $schema?: string;
+  /** Project language (python or typescript). */
+  language?: string;
+  /** Registry URL. */
+  registry?: string;
+  /** Path mappings for item types. */
+  paths?: Record<string, string>;
+}
diff --git a/typescript/src/cli/utils/config.ts b/typescript/src/cli/utils/config.ts
