@cpretzinger/boss-claude 1.0.0 → 1.0.2

package/lib/setup/README.md

@@ -0,0 +1,187 @@
+# Boss Claude Setup Utilities
+
+Automated setup and configuration utilities for Boss Claude infrastructure.
+
+## GitHub Repository Setup
+
+**File:** `lib/setup/github-repo.js`
+
+Automatically creates and configures the `boss-claude-memory` private repository for storing Boss Claude persistent data.
+
+### Features
+
+- ✅ **Auto-detection**: Checks if repository exists before creating
+- ✅ **Private by default**: Creates PRIVATE repository for security
+- ✅ **Error handling**: Comprehensive error messages for all failure cases
+- ✅ **Access verification**: Ensures write permissions are available
+- ✅ **Token flexibility**: Supports GITHUB_TOKEN env var or git config
+- ✅ **Idempotent**: Safe to run multiple times
+- ✅ **Auto-update**: Updates description and settings if repo exists
+
+### Usage
+
+#### Programmatic
+
+```javascript
+import { setupGitHubRepo } from './lib/setup/github-repo.js';
+
+const result = await setupGitHubRepo({ verbose: true });
+
+if (result.success) {
+  console.log('Repository ready:', result.url);
+  console.log('Clone URL:', result.cloneUrl);
+  console.log('Private:', result.isPrivate);
+  console.log('Created:', result.created);
+} else {
+  console.error('Setup failed:', result.error);
+}
+```
+
+#### CLI
+
+```bash
+# Run the test script
+node lib/setup/test-github-setup.js
+```
+
+### Configuration
+
+The module looks for GitHub token in this order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `git config --global github.token`
+
+**Set token via environment:**
+```bash
+export GITHUB_TOKEN=ghp_your_token_here
+```
+
+**Set token via git config:**
+```bash
+git config --global github.token ghp_your_token_here
+```
+
+### Return Object
+
+```typescript
+{
+  success: boolean;          // Overall success status
+  owner: string | null;      // GitHub username
+  repo: string;              // Repository name (boss-claude-memory)
+  url: string | null;        // Repository web URL
+  cloneUrl: string | null;   // Git clone URL
+  isPrivate: boolean;        // Privacy status
+  created: boolean;          // True if newly created, false if updated
+  error?: string;            // Error message (only if success=false)
+}
+```
+
+### Error Cases Handled
+
+| Error | Handling |
+|-------|----------|
+| **No GitHub token** | Clear instructions on how to set token |
+| **Invalid token** | Authentication failure message |
+| **Repository exists** | Updates settings instead of creating |
+| **No write access** | Permission denied error |
+| **Network failure** | Connection error with retry suggestion |
+| **Name conflict** | Repository name already taken |
+| **Public repo** | Warning message (allows continuation) |
+
+### Example Output
+
+**Creating new repository:**
+```
+🔧 Boss Claude GitHub Repository Setup
+
+ℹ GitHub token found
+ℹ Authenticated with GitHub
+ℹ GitHub user: cpretzinger
+ℹ Checking for existing repository...
+ℹ Creating private repository "boss-claude-memory"...
+✓ Repository created: https://github.com/cpretzinger/boss-claude-memory
+ℹ Verifying repository access...
+✓ Repository access verified
+
+✓ Setup Complete!
+
+Repository Details:
+  Owner: cpretzinger
+  Name: boss-claude-memory
+  URL: https://github.com/cpretzinger/boss-claude-memory
+  Private: Yes
+  Status: Created
+```
+
+**Updating existing repository:**
+```
+🔧 Boss Claude GitHub Repository Setup
+
+ℹ GitHub token found
+ℹ Authenticated with GitHub
+ℹ GitHub user: cpretzinger
+ℹ Checking for existing repository...
+ℹ Repository "boss-claude-memory" already exists
+ℹ Updating repository settings...
+ℹ Repository settings updated
+ℹ Verifying repository access...
+✓ Repository access verified
+
+✓ Setup Complete!
+
+Repository Details:
+  Owner: cpretzinger
+  Name: boss-claude-memory
+  URL: https://github.com/cpretzinger/boss-claude-memory
+  Private: Yes
+  Status: Updated
+```
+
+### Integration
+
+This module will be integrated into the Boss Claude installation process:
+
+```javascript
+// In scripts/install.js
+import { setupGitHubRepo } from '../lib/setup/github-repo.js';
+
+// During installation
+const repoSetup = await setupGitHubRepo({ verbose: false });
+if (!repoSetup.success) {
+  console.warn('GitHub repository setup skipped. Run manually later.');
+}
+```
+
+### Security
+
+- Repository is created as **PRIVATE by default**
+- Token is never logged or exposed
+- No sensitive data written to repository (handled separately)
+- Write access verified before proceeding
+
+### Testing
+
+```bash
+# Test with environment variable
+GITHUB_TOKEN=ghp_your_token node lib/setup/test-github-setup.js
+
+# Test with git config
+git config --global github.token ghp_your_token
+node lib/setup/test-github-setup.js
+```
+
+### Exported Functions
+
+```javascript
+// Main setup function
+setupGitHubRepo(options)
+
+// CLI command wrapper
+setupGitHubRepoCommand()
+
+// Helper functions (exported for testing)
+getGitHubToken()
+getGitHubUsername(octokit)
+repositoryExists(octokit, owner, repo)
+createRepository(octokit, repo)
+```