craftdesk 0.3.0 → 0.5.0

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"}

package/dist/commands/config.js

@@ -1,56 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createConfigCommand = createConfigCommand;
-const commander_1 = require("commander");
-const config_manager_1 = require("../services/config-manager");
-const logger_1 = require("../utils/logger");
-function createConfigCommand() {
-    const config = new commander_1.Command('config')
-        .description('Manage CraftDesk CLI configuration');
-    config
-        .command('list')
-        .description('List all configuration values')
-        .action(async () => {
-        await config_manager_1.configManager.list();
-    });
-    config
-        .command('get <key>')
-        .description('Get a configuration value')
-        .action(async (key) => {
-        const value = await config_manager_1.configManager.get(key);
-        if (value !== undefined) {
-            logger_1.logger.log(value);
-        }
-        else {
-            logger_1.logger.error(`Configuration key '${key}' not found`);
-            process.exit(1);
-        }
-    });
-    config
-        .command('set <key> <value>')
-        .description('Set a configuration value')
-        .action(async (key, value) => {
-        // Handle special cases
-        if (key.includes(':registry')) {
-            // Setting a scoped registry
-            // e.g., @acme:registry -> scopes.@acme
-            const scope = key.split(':')[0];
-            await config_manager_1.configManager.set(`scopes.${scope}`, value);
-            logger_1.logger.success(`Set registry for ${scope} to ${value}`);
-        }
-        else if (key.startsWith('//') && key.includes('/:token')) {
-            // Setting auth token
-            // e.g., //crafts.acme.com/:token -> auth.crafts.acme.com.token
-            const host = key.substring(2, key.indexOf('/:'));
-            await config_manager_1.configManager.set(`auth.${host}.token`, value);
-            logger_1.logger.success(`Set auth token for ${host}`);
-        }
-        else {
-            // Normal key-value
-            await config_manager_1.configManager.set(key, value);
-            logger_1.logger.success(`Set ${key} to ${value}`);
-        }
-    });
-    return config;
-}
-//# sourceMappingURL=config.js.map

package/dist/commands/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":";;AAIA,kDAiDC;AArDD,yCAAoC;AACpC,+DAA2D;AAC3D,4CAAyC;AAEzC,SAAgB,mBAAmB;IACjC,MAAM,MAAM,GAAG,IAAI,mBAAO,CAAC,QAAQ,CAAC;SACjC,WAAW,CAAC,oCAAoC,CAAC,CAAC;IAErD,MAAM;SACH,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,+BAA+B,CAAC;SAC5C,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,8BAAa,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,WAAW,CAAC;SACpB,WAAW,CAAC,2BAA2B,CAAC;SACxC,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,MAAM,8BAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,eAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACN,eAAM,CAAC,KAAK,CAAC,sBAAsB,GAAG,aAAa,CAAC,CAAC;YACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,MAAM;SACH,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,2BAA2B,CAAC;SACxC,MAAM,CAAC,KAAK,EAAE,GAAW,EAAE,KAAa,EAAE,EAAE;QAC3C,uBAAuB;QACvB,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC9B,4BAA4B;YAC5B,uCAAuC;YACvC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAChC,MAAM,8BAAa,CAAC,GAAG,CAAC,UAAU,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;YAClD,eAAM,CAAC,OAAO,CAAC,oBAAoB,KAAK,OAAO,KAAK,EAAE,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3D,qBAAqB;YACrB,+DAA+D;YAC/D,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACjD,MAAM,8BAAa,CAAC,GAAG,CAAC,QAAQ,IAAI,QAAQ,EAAE,KAAK,CAAC,CAAC;YACrD,eAAM,CAAC,OAAO,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,mBAAmB;YACnB,MAAM,8BAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACpC,eAAM,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types/config.d.ts

@@ -1,17 +0,0 @@
-export interface CraftDeskConfig {
-    registries?: {
-        default?: string;
-        [key: string]: string | undefined;
-    };
-    scopes?: {
-        [scope: string]: string;
-    };
-    auth?: {
-        [host: string]: {
-            token: string;
-        };
-    };
-    installPath?: string;
-    cache?: string;
-}
-//# sourceMappingURL=config.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE;QACX,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KACnC,CAAC;IAEF,MAAM,CAAC,EAAE;QACP,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;IAEF,IAAI,CAAC,EAAE;QACL,CAAC,IAAI,EAAE,MAAM,GAAG;YACd,KAAK,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC;IAEF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types/config.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":""}

package/docs/DEPENDENCY_RESOLUTION.md

@@ -1,237 +0,0 @@
-# CraftDesk Dependency Resolution
-
-## Overview
-
-CraftDesk supports multiple dependency sources and resolves them intelligently, including transitive dependencies.
-
-## Dependency Sources
-
-### 1. Registry Dependencies (Default)
-
-Standard dependencies are fetched from registries:
-
-```json
-{
-  "dependencies": {
-    "ruby-on-rails": "^7.0.0"
-  }
-}
-```
-
-**Resolution Process:**
-1. Query the registry API for package metadata
-2. Resolve version constraints
-3. Fetch transitive dependencies
-4. Generate lockfile with exact versions
-
-### 2. Git Dependencies
-
-Dependencies can be fetched directly from git repositories:
-
-```json
-{
-  "dependencies": {
-    "my-skill": {
-      "git": "https://github.com/user/repo.git",
-      "branch": "main"
-    }
-  }
-}
-```
-
-**Resolution Process:**
-1. Clone the repository (shallow clone for efficiency)
-2. Check out specified branch/tag/commit
-3. Look for `craftdesk.json` in the repository
-4. Extract metadata and dependencies
-5. Recursively resolve any dependencies found
-
-## Handling Missing craftdesk.json
-
-When a git dependency doesn't have a `craftdesk.json` file, the CLI:
-
-### 1. Generates Minimal Metadata
-
-```json
-{
-  "name": "repository-name",
-  "version": "branch-or-tag-or-commit",
-  "type": "skill",  // Inferred from structure
-  "description": "Git dependency from <url>",
-  "dependencies": {}
-}
-```
-
-### 2. Type Inference
-
-The system tries to infer the craft type by looking for:
-
-1. **Marker Files:**
-   - `SKILL.md` → type: "skill"
-   - `AGENT.md` → type: "agent"
-   - `COMMAND.md` → type: "command"
-   - `HOOK.md` → type: "hook"
-
-2. **Directory Name Patterns:**
-   - Contains "skill" → type: "skill"
-   - Contains "agent" → type: "agent"
-   - Contains "command" → type: "command"
-   - Contains "hook" → type: "hook"
-
-3. **Default:** type: "skill"
-
-## Monorepo Support
-
-For git repositories containing multiple crafts:
-
-```json
-{
-  "dependencies": {
-    "auth-handler": {
-      "git": "https://github.com/company/monorepo.git",
-      "tag": "v3.0.0",
-      "path": "packages/auth"
-    },
-    "data-processor": {
-      "git": "https://github.com/company/monorepo.git",
-      "tag": "v3.0.0",
-      "path": "agents/processor"
-    }
-  }
-}
-```
-
-The CLI:
-1. Clones the repository once
-2. Looks for `craftdesk.json` in each specified `path`
-3. Installs only the contents of the specified subdirectory
-
-## Transitive Dependencies
-
-### From Registry Packages
-
-Registry packages include their dependencies in metadata:
-```json
-{
-  "name": "ruby-on-rails",
-  "version": "7.1.0",
-  "dependencies": {
-    "activerecord": "^7.1.0",
-    "actionpack": "^7.1.0"
-  }
-}
-```
-
-### From Git Packages
-
-Git packages' dependencies are discovered by reading their `craftdesk.json`:
-```json
-// In https://github.com/user/my-skill.git/craftdesk.json
-{
-  "name": "my-skill",
-  "version": "2.0.0",
-  "dependencies": {
-    "postgres-expert": "^1.0.0",  // Will be resolved from registry
-    "helper-lib": {
-      "git": "https://github.com/user/helper.git"  // Will be resolved from git
-    }
-  }
-}
-```
-
-## Resolution Algorithm
-
-```typescript
-1. Start with direct dependencies from craftdesk.json
-2. For each dependency:
-   a. If registry: Query API for metadata
-   b. If git: Clone and extract craftdesk.json
-3. Add discovered dependencies to resolution queue
-4. Repeat until all dependencies resolved
-5. Check for version conflicts
-6. Generate lockfile with exact versions
-```
-
-## Lockfile Structure
-
-The lockfile captures the complete resolution:
-
-```json
-{
-  "version": "1.0.0",
-  "lockfileVersion": 1,
-  "crafts": {
-    "my-skill": {
-      "version": "2.0.0",
-      "resolved": "https://github.com/user/my-skill.git",
-      "integrity": "abc123def456",  // Git commit hash
-      "type": "skill",
-      "git": "https://github.com/user/my-skill.git",
-      "branch": "main",
-      "commit": "abc123def456789012345678901234567890abcd",
-      "dependencies": {
-        "postgres-expert": "^1.0.0"
-      }
-    },
-    "postgres-expert": {
-      "version": "1.2.3",
-      "resolved": "https://craftdesk.ai/api/v1/crafts/anthropic/postgres-expert/versions/1.2.3/download",
-      "integrity": "sha256-xyz789...",
-      "type": "agent",
-      "registry": "https://craftdesk.ai",
-      "dependencies": {}
-    }
-  }
-}
-```
-
-## Error Handling
-
-### Missing Dependencies
-- Git repos without craftdesk.json: Generate minimal metadata
-- Unreachable git repos: Fail with clear error message
-- Registry packages not found: Fail with suggestions
-
-### Version Conflicts
-- Currently: Last-write-wins
-- Future: Interactive conflict resolution
-
-### Circular Dependencies
-- Detected during resolution
-- Fails with error showing the circular chain
-
-## Performance Optimizations
-
-1. **Shallow Clones:** Git repos cloned with `--depth 1`
-2. **Parallel Resolution:** Registry queries run in parallel
-3. **Caching:** Git repos cached for 15 minutes during resolution
-4. **Minimal Transfers:** Only specified subdirectories copied for monorepos
-
-## Example: Mixed Resolution
-
-Given this `craftdesk.json`:
-```json
-{
-  "dependencies": {
-    "ruby-on-rails": "^7.0.0",
-    "custom-auth": {
-      "git": "https://github.com/company/auth.git",
-      "branch": "main"
-    }
-  }
-}
-```
-
-Resolution steps:
-1. Query registry for ruby-on-rails@^7.0.0
-   - Resolves to 7.1.2
-   - Has dependencies: activerecord@^7.1.0, actionpack@^7.1.0
-2. Clone https://github.com/company/auth.git
-   - Check out main branch
-   - Read craftdesk.json
-   - Has dependency: jwt-helper@^2.0.0
-3. Resolve transitive dependencies:
-   - activerecord@^7.1.0 → 7.1.0
-   - actionpack@^7.1.0 → 7.1.0
-   - jwt-helper@^2.0.0 → 2.1.0
-4. Generate complete lockfile with all 5 packages

package/examples/craftdesk-all-sources.json

@@ -1,79 +0,0 @@
-{
-  "name": "full-example-project",
-  "version": "1.0.0",
-  "type": "skill",
-  "description": "Example showing all dependency source types",
-
-  "dependencies": {
-    // Registry dependencies (default)
-    "ruby-on-rails": "^7.0.0",
-    "postgres-expert": "~1.2.0",
-
-    // Registry with custom registry
-    "@company/private-skill": {
-      "version": "^3.0.0",
-      "registry": "company-private"
-    },
-
-    // Direct registry URL
-    "special-tool": {
-      "version": "^2.0.0",
-      "registry": "https://tools.example.com"
-    },
-
-    // Git dependencies with branch
-    "experimental-agent": {
-      "git": "https://github.com/user/agent-repo.git",
-      "branch": "develop"
-    },
-
-    // Git with specific tag
-    "stable-skill": {
-      "git": "https://github.com/org/skills.git",
-      "tag": "v2.1.0"
-    },
-
-    // Git with subdirectory (monorepo)
-    "auth-handler": {
-      "git": "https://github.com/company/monorepo.git",
-      "branch": "main",
-      "path": "packages/auth"
-    },
-
-    // Git with commit hash
-    "specific-version": {
-      "git": "https://github.com/user/repo.git",
-      "commit": "a1b2c3d4e5f6789012345678901234567890abcd"
-    },
-
-    // Multiple skills from same git repo
-    "data-processor": {
-      "git": "https://github.com/company/monorepo.git",
-      "tag": "v1.0.0",
-      "path": "skills/data-processor"
-    },
-    "report-generator": {
-      "git": "https://github.com/company/monorepo.git",
-      "tag": "v1.0.0",
-      "path": "skills/report-generator"
-    }
-  },
-
-  "devDependencies": {
-    "test-runner": "^1.0.0",
-    "code-reviewer": {
-      "git": "https://github.com/tools/reviewer.git",
-      "branch": "latest"
-    }
-  },
-
-  "registries": {
-    "default": {
-      "url": "https://craftdesk.ai"
-    },
-    "company-private": {
-      "url": "https://registry.company.com",
-      "scope": "@company"
-    }
-  }
-}