craftdesk 0.3.0 → 0.4.0

package/API.md

@@ -1,414 +0,0 @@
-# CraftDesk CLI API Documentation
-
-## Overview
-
-This document describes the internal API for the CraftDesk CLI, useful for contributors and developers extending the functionality.
-
-## Core Services
-
-### ConfigManager
-
-Manages configuration and registry resolution.
-
-```typescript
-import { configManager } from './services/config-manager';
-```
-
-#### Methods
-
-##### `getRegistryForPackage(packageName: string): Promise<string>`
-
-Returns the appropriate registry URL for a given package.
-
-**Parameters:**
-- `packageName` - Package name (may be scoped like `@company/package`)
-
-**Returns:** Registry URL
-
-**Example:**
-```typescript
-const registry = await configManager.getRegistryForPackage('@company/auth');
-// Returns: 'https://company.internal' (if configured)
-```
-
-##### `getAuthToken(registryName: string): Promise<string | null>`
-
-Gets authentication token from environment variables.
-
-**Parameters:**
-- `registryName` - Registry name from craftdesk.json
-
-**Returns:** Auth token or null
-
-**Environment Variable Format:** `CRAFTDESK_AUTH_{REGISTRY_NAME_UPPERCASE}`
-
-**Example:**
-```typescript
-// Looks for CRAFTDESK_AUTH_COMPANY_PRIVATE
-const token = await configManager.getAuthToken('company-private');
-```
-
-##### `getInstallPath(): string`
-
-Returns the installation directory path.
-
-**Returns:** `.claude` (relative path)
-
-##### `getCraftDeskJson(): Promise<CraftDeskJson | null>`
-
-Reads and caches the craftdesk.json file.
-
-**Returns:** Parsed craftdesk.json or null if not found
-
----
-
-### GitResolver
-
-Resolves git dependencies and extracts metadata.
-
-```typescript
-import { GitResolver } from './services/git-resolver';
-
-const resolver = new GitResolver();
-```
-
-#### Methods
-
-##### `resolveGitDependency(gitInfo: GitDependencyInfo): Promise<GitDependencyInfo>`
-
-Resolves a git dependency by cloning and reading metadata.
-
-**Parameters:**
-```typescript
-interface GitDependencyInfo {
-  url: string;
-  branch?: string;
-  tag?: string;
-  commit?: string;
-  path?: string;
-  craftDeskJson?: CraftDeskJson;
-  resolvedCommit?: string;
-}
-```
-
-**Returns:** Enhanced GitDependencyInfo with craftdesk.json and resolved commit
-
-**Example:**
-```typescript
-const info = await resolver.resolveGitDependency({
-  url: 'https://github.com/company/auth.git',
-  branch: 'main',
-  path: 'packages/auth'
-});
-
-console.log(info.craftDeskJson.name);     // 'auth-skill'
-console.log(info.resolvedCommit);          // Full commit hash
-```
-
-##### `resolveAllDependencies(dependencies: Record<string, string | DependencyConfig>): Promise<{resolved, lockfile}>`
-
-Resolves all dependencies including transitive dependencies.
-
-**Parameters:**
-- `dependencies` - Map of dependency names to version strings or config objects
-
-**Returns:**
-```typescript
-{
-  resolved: Record<string, any>;  // All resolved dependencies
-  lockfile: {                     // Generated lockfile structure
-    version: string;
-    lockfileVersion: number;
-    crafts: Record<string, any>;
-  }
-}
-```
-
-**Example:**
-```typescript
-const result = await resolver.resolveAllDependencies({
-  'ruby-on-rails': '^7.0.0',
-  'custom-auth': {
-    git: 'https://github.com/company/auth.git',
-    branch: 'main'
-  }
-});
-```
-
----
-
-### Installer
-
-Handles installation of crafts from various sources.
-
-```typescript
-import { Installer } from './services/installer';
-
-const installer = new Installer();
-```
-
-#### Methods
-
-##### `installFromLockfile(lockfile: CraftDeskLock): Promise<void>`
-
-Installs all crafts defined in a lockfile.
-
-**Parameters:**
-```typescript
-interface CraftDeskLock {
-  version: string;
-  lockfileVersion: number;
-  crafts: Record<string, LockEntry>;
-}
-```
-
-**Throws:** Error if any craft fails to install
-
-**Example:**
-```typescript
-const lockfile = await readLockfile();
-await installer.installFromLockfile(lockfile);
-```
-
-##### `installCraft(name: string, entry: LockEntry): Promise<void>`
-
-Installs a single craft.
-
-**Parameters:**
-- `name` - Craft name
-- `entry` - Lockfile entry with installation details
-
-**Example:**
-```typescript
-await installer.installCraft('ruby-on-rails', {
-  version: '7.1.0',
-  resolved: 'https://craftdesk.ai/download/...',
-  type: 'skill',
-  dependencies: {}
-});
-```
-
----
-
-### RegistryClient
-
-Communicates with CraftDesk registries.
-
-```typescript
-import { registryClient } from './services/registry-client';
-```
-
-#### Methods
-
-##### `getCraftInfo(name: string, version?: string, registry?: string): Promise<CraftInfo | null>`
-
-Fetches craft information from registry.
-
-**Parameters:**
-- `name` - Craft name
-- `version` - Optional version constraint
-- `registry` - Optional registry URL override
-
-**Returns:** Craft metadata or null if not found
-
-**Example:**
-```typescript
-const info = await registryClient.getCraftInfo('ruby-on-rails', '^7.0.0');
-console.log(info.version);  // '7.1.0'
-```
-
----
-
-## Type Definitions
-
-### CraftDeskJson
-
-```typescript
-interface CraftDeskJson {
-  name: string;
-  version: string;
-  type: 'skill' | 'agent' | 'command' | 'hook';
-  description?: string;
-  author?: string;
-  dependencies?: Record<string, string | DependencyConfig>;
-  devDependencies?: Record<string, string | DependencyConfig>;
-  registries?: Record<string, RegistryConfig>;
-}
-```
-
-### DependencyConfig
-
-```typescript
-interface DependencyConfig {
-  version?: string;      // For registry deps
-  registry?: string;     // Custom registry URL
-  git?: string;          // Git repository URL
-  branch?: string;       // Git branch
-  tag?: string;          // Git tag
-  commit?: string;       // Git commit hash
-  path?: string;         // Subdirectory path for monorepos
-}
-```
-
-### RegistryConfig
-
-```typescript
-interface RegistryConfig {
-  url: string;
-  scope?: string;        // Scope for scoped packages (@company)
-  auth?: string;         // DEPRECATED: Use environment variables
-}
-```
-
-### LockEntry
-
-```typescript
-interface LockEntry {
-  version: string;
-  resolved: string;      // Download URL or git URL
-  integrity: string;     // SHA-256 hash or commit hash
-  type: 'skill' | 'agent' | 'command' | 'hook';
-  author?: string;
-  dependencies: Record<string, string>;
-
-  // Git-specific fields
-  git?: string;
-  branch?: string;
-  tag?: string;
-  commit?: string;
-  path?: string;
-
-  // Registry-specific fields
-  registry?: string;
-}
-```
-
----
-
-## Utility Functions
-
-### File System Utilities
-
-```typescript
-import { readCraftDeskJson, writeCraftDeskJson, ensureDir } from './utils/file-system';
-```
-
-#### `readCraftDeskJson(): Promise<CraftDeskJson | null>`
-
-Reads craftdesk.json from current directory.
-
-#### `writeCraftDeskJson(data: CraftDeskJson): Promise<void>`
-
-Writes craftdesk.json to current directory.
-
-#### `ensureDir(dirPath: string): Promise<void>`
-
-Creates directory if it doesn't exist.
-
-### Logger
-
-```typescript
-import { logger } from './utils/logger';
-```
-
-#### Methods
-
-- `info(message: string)` - Info message
-- `success(message: string)` - Success message (green)
-- `error(message: string)` - Error message (red)
-- `warn(message: string)` - Warning message (yellow)
-- `debug(message: string)` - Debug message (if verbose)
-- `startSpinner(message: string)` - Start loading spinner
-- `updateSpinner(message: string)` - Update spinner message
-- `succeedSpinner(message?: string)` - Stop spinner with success
-- `failSpinner(message?: string)` - Stop spinner with failure
-
----
-
-## Extension Points
-
-### Adding New Craft Types
-
-1. Update type definition in `src/types/craftdesk-json.ts`:
-
-```typescript
-export type CraftType = 'skill' | 'agent' | 'command' | 'hook' | 'your-new-type';
-```
-
-2. Update installer's `getTypeDirectory()` method:
-
-```typescript
-private getTypeDirectory(type: CraftType): string {
-  switch (type) {
-    case 'your-new-type':
-      return 'your-types';
-    // ...
-  }
-}
-```
-
-3. Update git-resolver's `inferCraftType()` method:
-
-```typescript
-if (files.includes('YOUR_TYPE.md')) return 'your-new-type';
-```
-
-### Adding New Commands
-
-1. Create command file in `src/commands/`:
-
-```typescript
-import { Command } from 'commander';
-
-export function createYourCommand(): Command {
-  return new Command('your-command')
-    .description('Your command description')
-    .action(async () => {
-      // Implementation
-    });
-}
-```
-
-2. Register in `src/index.ts`:
-
-```typescript
-import { createYourCommand } from './commands/your-command';
-
-program.addCommand(createYourCommand());
-```
-
-### Adding New Dependency Sources
-
-1. Update `DependencyConfig` interface
-2. Modify `GitResolver.resolveAllDependencies()` to handle new source type
-3. Update `Installer.installCraft()` to support new installation method
-
----
-
-## Error Handling
-
-All service methods may throw errors. Wrap calls in try-catch:
-
-```typescript
-try {
-  await installer.installCraft(name, entry);
-} catch (error) {
-  logger.error(`Installation failed: ${error.message}`);
-  process.exit(1);
-}
-```
-
-## Testing
-
-See [TESTING.md](./TESTING.md) for testing guidelines and examples.
-
-## Contributing
-
-When adding new functionality:
-
-1. Add JSDoc comments to all public functions
-2. Include usage examples in documentation
-3. Add unit tests for new functions
-4. Update integration tests if CLI behavior changes
-5. Update type definitions
-6. Add inline comments for complex algorithms

package/TESTING.md

@@ -1,263 +0,0 @@
-# Testing Guide
-
-## Overview
-
-The CraftDesk CLI uses **Vitest** as its testing framework, providing fast and modern testing capabilities with TypeScript support.
-
-## Test Structure
-
-```
-tests/
-├── unit/                    # Unit tests for individual modules
-│   ├── config-manager.test.ts
-│   ├── git-resolver.test.ts
-│   └── installer.test.ts
-├── integration/             # Integration tests for CLI commands
-│   ├── init-command.test.ts
-│   └── list-command.test.ts
-├── fixtures/                # Test fixtures and mock data
-│   ├── craftdesk.json
-│   └── craftdesk-git.json
-└── helpers/                 # Test utilities
-    └── test-utils.ts
-```
-
-## Running Tests
-
-### Run all tests
-```bash
-npm test
-```
-
-### Run tests in watch mode
-```bash
-npm run test:watch
-```
-
-### Run tests with coverage
-```bash
-npm run test:coverage
-```
-
-### Run tests with UI
-```bash
-npm run test:ui
-```
-
-## Test Coverage
-
-Coverage reports are generated using Vitest's built-in coverage tool (v8 provider).
-
-### Viewing Coverage
-
-After running `npm run test:coverage`, view the report:
-
-```bash
-# Terminal summary is displayed automatically
-
-# Open HTML report in browser
-open coverage/index.html
-```
-
-### Coverage Thresholds
-
-Current coverage configuration in `vitest.config.ts`:
-- Excludes: `node_modules/`, `dist/`, `bin/`, test files
-
-## Writing Tests
-
-### Unit Tests
-
-Unit tests focus on testing individual functions and classes in isolation.
-
-**Example: Testing ConfigManager**
-
-```typescript
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { ConfigManager } from '../../src/services/config-manager';
-import { createTempDir, cleanupTempDir } from '../helpers/test-utils';
-
-describe('ConfigManager', () => {
-  let configManager: ConfigManager;
-  let tempDir: string;
-
-  beforeEach(async () => {
-    configManager = new ConfigManager();
-    tempDir = await createTempDir('config-test-');
-    process.chdir(tempDir);
-  });
-
-  afterEach(async () => {
-    await cleanupTempDir(tempDir);
-  });
-
-  it('should return default registry when no craftdesk.json exists', async () => {
-    const registry = await configManager.getRegistryForPackage('test-package');
-    expect(registry).toBe('https://craftdesk.ai');
-  });
-});
-```
-
-### Integration Tests
-
-Integration tests verify that CLI commands work correctly end-to-end.
-
-**Example: Testing CLI Commands**
-
-```typescript
-import { execSync } from 'child_process';
-import path from 'path';
-
-describe('craftdesk init command', () => {
-  const cliPath = path.join(__dirname, '../../dist/index.js');
-
-  it('should create a new craftdesk.json file', () => {
-    execSync(`node ${cliPath} init --name test --version 1.0.0 --type skill`);
-
-    const exists = await fs.pathExists('craftdesk.json');
-    expect(exists).toBe(true);
-  });
-});
-```
-
-### Test Utilities
-
-The `tests/helpers/test-utils.ts` file provides helper functions:
-
-- `createTempDir(prefix)` - Creates a temporary test directory
-- `cleanupTempDir(dirPath)` - Removes a temporary directory
-- `copyFixture(name, targetDir)` - Copies a fixture file
-- `readJsonFile(path)` - Reads and parses JSON file
-- `writeJsonFile(path, data)` - Writes JSON to file
-- `createMockCraftInfo(name, version)` - Creates mock craft metadata
-
-### Mocking
-
-Use Vitest's built-in mocking for external dependencies:
-
-```typescript
-import { vi } from 'vitest';
-import { execSync } from 'child_process';
-
-vi.mock('child_process', () => ({
-  execSync: vi.fn()
-}));
-
-// In your test
-const mockExecSync = vi.mocked(execSync);
-mockExecSync.mockReturnValue(Buffer.from('output'));
-```
-
-## CI/CD Integration
-
-### GitHub Actions
-
-The `.github/workflows/ci.yml` file runs tests automatically on:
-- Push to main/master/develop branches
-- Pull requests to main/master/develop branches
-
-The workflow:
-1. Tests on Node.js 16.x, 18.x, and 20.x
-2. Generates coverage report (Node 20.x only)
-3. Uploads coverage to Codecov
-4. Verifies TypeScript compilation
-5. Builds the project
-
-### Local CI Simulation
-
-Run the same checks locally before pushing:
-
-```bash
-# Run tests
-npm test
-
-# Generate coverage
-npm run test:coverage
-
-# Type check
-npx tsc --noEmit
-
-# Build
-npm run build
-```
-
-## Test Best Practices
-
-### 1. Isolation
-- Each test should be independent
-- Use `beforeEach` and `afterEach` for setup/teardown
-- Clean up temporary files and directories
-
-### 2. Descriptive Names
-```typescript
-// Good
-it('should return scoped registry for scoped package')
-
-// Bad
-it('test1')
-```
-
-### 3. Arrange-Act-Assert Pattern
-```typescript
-it('should parse git URL with branch', () => {
-  // Arrange
-  const url = 'https://github.com/user/repo.git#main';
-
-  // Act
-  const result = parseGitUrl(url);
-
-  // Assert
-  expect(result.branch).toBe('main');
-  expect(result.url).toBe('https://github.com/user/repo.git');
-});
-```
-
-### 4. Test Edge Cases
-- Empty inputs
-- Invalid data
-- Error conditions
-- Boundary values
-
-### 5. Mock External Dependencies
-- File system operations (when appropriate)
-- Network requests
-- Child processes
-- Environment variables
-
-## Debugging Tests
-
-### Run specific test file
-```bash
-npm test tests/unit/config-manager.test.ts
-```
-
-### Run tests matching pattern
-```bash
-npm test -- --grep "git dependency"
-```
-
-### Debug with breakpoints
-```bash
-node --inspect-brk ./node_modules/.bin/vitest run
-```
-
-Then attach your debugger (VS Code, Chrome DevTools, etc.)
-
-## Continuous Improvement
-
-### Coverage Goals
-- Maintain >80% code coverage
-- Focus on critical paths first
-- Add tests when fixing bugs
-
-### Test Maintenance
-- Update tests when changing functionality
-- Remove obsolete tests
-- Keep test data fixtures up to date
-- Review test failures in CI promptly
-
-## Resources
-
-- [Vitest Documentation](https://vitest.dev/)
-- [Testing Library Best Practices](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)
-- [Effective Testing Strategies](https://martinfowler.com/articles/practical-test-pyramid.html)

package/dist/commands/config.d.ts

@@ -1,3 +0,0 @@
-import { Command } from 'commander';
-export declare function createConfigCommand(): Command;
-//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,mBAAmB,IAAI,OAAO,CAiD7C"}