cskit-cli 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# CSK CLI
+
+> Content Suite Kit Command Line Interface
+
+CLI tool để download và quản lý CSK từ private GitHub repository.
+
+## Installation
+
+```bash
+npm install -g csk-cli
+```
+
+## Prerequisites
+
+- Node.js >= 16
+- GitHub Personal Access Token (granted after purchase)
+
+## Quick Start
+
+```bash
+# 1. Authenticate with GitHub
+csk auth --login
+
+# 2. Initialize CSK in your project
+cd your-project
+csk init
+
+# 3. Check status
+csk status
+```
+
+## Commands
+
+### `csk auth`
+
+Manage GitHub authentication.
+
+```bash
+csk auth --login   # Add/update GitHub token
+csk auth --logout  # Remove stored token
+csk auth --status  # Check auth status (default)
+```
+
+**Token storage priority:**
+1. Environment variable (`GITHUB_TOKEN` or `GH_TOKEN`)
+2. GitHub CLI (`gh auth token`)
+3. OS Keychain (macOS Keychain, Windows Credential Manager, Linux libsecret)
+4. Config file (`~/.csk/config.json`)
+
+### `csk init`
+
+Download/update CSK in current project.
+
+```bash
+csk init           # Smart merge (preserve user changes)
+csk init --force   # Force overwrite (except protected files)
+csk init --no-merge # Skip merge, overwrite all
+```
+
+**Protected files (never overwritten):**
+- `.env`, `.env.local`, `.env.production`
+- `*.key`, `*.pem`
+- `config.local.json`
+
+### `csk status`
+
+Check installation status.
+
+```bash
+csk status
+```
+
+Shows:
+- Authentication status
+- Installation version
+- Directory status
+
+### `csk update`
+
+Update CLI tool to latest version.
+
+```bash
+csk update
+```
+
+## Creating a GitHub PAT
+
+1. Go to [GitHub Settings > Tokens](https://github.com/settings/tokens/new)
+2. Select scopes:
+   - `repo` (Full control of private repositories)
+3. Generate token
+4. Run `csk auth --login` and paste token
+
+## Support
+
+- Website: https://cskit.net
+- Email: support@cskit.net
+
+## License
+
+MIT

package/bin/csk.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../src/index.js');

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "cskit-cli",
+  "version": "1.0.0",
+  "description": "Content Suite Kit CLI - Download and manage CSK skills from private repository",
+  "main": "src/index.js",
+  "bin": {
+    "cskit": "bin/csk.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "content",
+    "skills",
+    "cli",
+    "ai"
+  ],
+  "author": {
+    "name": "To Trieu",
+    "email": "contact@tohaitrieu.net",
+    "url": "https://cskit.net"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tohaitrieu/csk-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tohaitrieu/csk-cli/issues"
+  },
+  "homepage": "https://cskit.net",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.6",
+    "keytar": "^7.9.0",
+    "ora": "^5.4.1",
+    "simple-git": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ]
+}

package/src/commands/auth.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * Auth Command
+ *
+ * Manages GitHub authentication for accessing private CSK repository.
+ * Supports multiple token sources with fallback chain.
+ */
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const ora = require('ora');
+const { storeToken, getToken, deleteToken, getTokenSource } = require('../lib/keychain');
+const { verifyAccess } = require('../lib/github');
+
+/**
+ * Main auth command handler
+ * @param {Object} options - Command options
+ */
+async function authCommand(options) {
+  if (options.login) {
+    await login();
+  } else if (options.logout) {
+    await logout();
+  } else {
+    // Default: show status
+    await showStatus();
+  }
+}
+
+/**
+ * Login - add or update GitHub token
+ */
+async function login() {
+  console.log(chalk.cyan('\n  GitHub Authentication\n'));
+
+  console.log(chalk.dim('  CSK requires a GitHub Personal Access Token (PAT) to download'));
+  console.log(chalk.dim('  from the private repository.\n'));
+
+  console.log(chalk.yellow('  Create a token at:'));
+  console.log(chalk.blue('  https://github.com/settings/tokens/new\n'));
+
+  console.log(chalk.dim('  Required scopes:'));
+  console.log(chalk.dim('  - repo (Full control of private repositories)\n'));
+
+  // Prompt for token
+  const { token } = await inquirer.prompt([
+    {
+      type: 'password',
+      name: 'token',
+      message: 'Enter your GitHub PAT:',
+      mask: '*',
+      validate: (input) => {
+        if (!input || input.trim().length === 0) {
+          return 'Token is required';
+        }
+        if (!input.startsWith('ghp_') && !input.startsWith('github_pat_')) {
+          return 'Invalid token format. Should start with ghp_ or github_pat_';
+        }
+        return true;
+      }
+    }
+  ]);
+
+  // Verify token
+  const spinner = ora('Verifying token...').start();
+
+  const { valid, error } = await verifyAccess(token.trim());
+
+  if (!valid) {
+    spinner.fail(chalk.red('Token verification failed'));
+    console.log(chalk.red(`\n  ${error}`));
+    console.log(chalk.dim('\n  Make sure you have been granted access to the CSK repository.'));
+    console.log(chalk.dim('  If you purchased CSK, please accept the GitHub invitation first.\n'));
+    process.exit(1);
+  }
+
+  spinner.text = 'Storing token...';
+
+  // Store token
+  const { success, method } = await storeToken(token.trim());
+
+  if (success) {
+    spinner.succeed(chalk.green('Authentication successful'));
+    console.log(chalk.dim(`\n  Token stored in: ${method}`));
+    console.log(chalk.green('\n  You can now use `csk init` to download CSK.\n'));
+  } else {
+    spinner.fail(chalk.red('Failed to store token'));
+    process.exit(1);
+  }
+}
+
+/**
+ * Logout - remove stored token
+ */
+async function logout() {
+  const spinner = ora('Removing stored token...').start();
+
+  const deleted = await deleteToken();
+
+  if (deleted) {
+    spinner.succeed(chalk.green('Token removed'));
+    console.log(chalk.dim('\n  You will need to authenticate again to use csk init.\n'));
+  } else {
+    spinner.info(chalk.yellow('No stored token found'));
+  }
+}
+
+/**
+ * Show authentication status
+ */
+async function showStatus() {
+  console.log(chalk.cyan('\n  Authentication Status\n'));
+
+  const spinner = ora('Checking authentication...').start();
+
+  const token = await getToken();
+  const source = await getTokenSource();
+
+  if (!token) {
+    spinner.fail(chalk.red('Not authenticated'));
+    console.log(chalk.dim('\n  Run `csk auth --login` to add your GitHub token.\n'));
+    return;
+  }
+
+  // Verify token still works
+  const { valid, error } = await verifyAccess(token);
+
+  if (valid) {
+    spinner.succeed(chalk.green('Authenticated'));
+    console.log(chalk.dim(`\n  Token source: ${formatSource(source)}`));
+    console.log(chalk.green('  Repository access: Verified\n'));
+  } else {
+    spinner.fail(chalk.red('Authentication invalid'));
+    console.log(chalk.dim(`\n  Token source: ${formatSource(source)}`));
+    console.log(chalk.red(`  Error: ${error}`));
+    console.log(chalk.dim('\n  Run `csk auth --login` to update your token.\n'));
+  }
+}
+
+/**
+ * Format token source for display
+ */
+function formatSource(source) {
+  const sources = {
+    'env': 'Environment variable (GITHUB_TOKEN or GH_TOKEN)',
+    'gh-cli': 'GitHub CLI (gh auth)',
+    'keychain': 'OS Keychain',
+    'config': 'Config file (~/.csk/config.json)',
+    'none': 'None'
+  };
+  return sources[source] || source;
+}
+
+module.exports = authCommand;

package/src/commands/init.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Init Command
+ *
+ * Downloads CSK from private GitHub repository into current project.
+ * Handles smart merging to preserve user modifications.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const ora = require('ora');
+const crypto = require('crypto');
+const { getToken } = require('../lib/keychain');
+const { verifyAccess, getRepoTree, downloadFile, getLatestRelease } = require('../lib/github');
+const {
+  isProtected,
+  shouldExclude,
+  determineMergeAction,
+  loadManifest,
+  saveManifest,
+  ensureDir
+} = require('../lib/merge');
+
+/**
+ * Main init command handler
+ * @param {Object} options - Command options
+ */
+async function initCommand(options) {
+  const projectDir = process.cwd();
+
+  console.log(chalk.cyan('\n  Content Suite Kit - Init\n'));
+
+  // Check authentication
+  const spinner = ora('Checking authentication...').start();
+
+  const token = await getToken();
+  if (!token) {
+    spinner.fail(chalk.red('Not authenticated'));
+    console.log(chalk.dim('\n  Run `csk auth --login` first.\n'));
+    process.exit(1);
+  }
+
+  // Verify access
+  const { valid, error } = await verifyAccess(token);
+  if (!valid) {
+    spinner.fail(chalk.red('Access denied'));
+    console.log(chalk.red(`\n  ${error}`));
+    process.exit(1);
+  }
+
+  spinner.succeed('Authenticated');
+
+  // Check for existing installation
+  const manifest = loadManifest(projectDir);
+  const isUpdate = manifest.version !== null;
+
+  if (isUpdate) {
+    console.log(chalk.dim(`\n  Existing installation found: v${manifest.version}`));
+    console.log(chalk.dim(`  Installed: ${manifest.installedAt}\n`));
+  }
+
+  // Get latest version
+  spinner.start('Fetching latest version...');
+
+  let version = 'main';
+  const release = await getLatestRelease(token);
+  if (release) {
+    version = release.tag;
+    spinner.succeed(`Latest version: ${release.tag}`);
+  } else {
+    spinner.info('No releases found, using main branch');
+  }
+
+  // Get file tree
+  spinner.start('Fetching file list...');
+
+  const tree = await getRepoTree(token);
+  const files = tree.filter(item =>
+    item.type === 'blob' && !shouldExclude(item.path)
+  );
+
+  spinner.succeed(`Found ${files.length} files`);
+
+  // Download and merge files
+  console.log(chalk.cyan('\n  Downloading files...\n'));
+
+  const stats = {
+    created: 0,
+    updated: 0,
+    skipped: 0,
+    protected: 0,
+    userModified: 0
+  };
+
+  const newManifest = {
+    files: {},
+    version: version,
+    installedAt: new Date().toISOString()
+  };
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const targetPath = path.join(projectDir, file.path);
+    const relativePath = file.path;
+
+    // Progress indicator
+    const progress = `[${i + 1}/${files.length}]`;
+
+    try {
+      // Download file content
+      const content = await downloadFile(token, file.path);
+      const contentHash = crypto.createHash('md5').update(content).digest('hex');
+
+      // Determine action
+      const { action, reason } = options.force
+        ? { action: isProtected(relativePath) ? 'skip' : 'update', reason: 'forced' }
+        : determineMergeAction(targetPath, relativePath, content, manifest.files);
+
+      // Execute action
+      switch (action) {
+        case 'create':
+          ensureDir(path.dirname(targetPath));
+          fs.writeFileSync(targetPath, content);
+          console.log(chalk.green(`  ${progress} + ${relativePath}`));
+          stats.created++;
+          newManifest.files[relativePath] = contentHash;
+          break;
+
+        case 'update':
+          ensureDir(path.dirname(targetPath));
+          fs.writeFileSync(targetPath, content);
+          console.log(chalk.blue(`  ${progress} ~ ${relativePath}`));
+          stats.updated++;
+          newManifest.files[relativePath] = contentHash;
+          break;
+
+        case 'skip':
+          if (reason === 'protected') {
+            console.log(chalk.yellow(`  ${progress} ! ${relativePath} (protected)`));
+            stats.protected++;
+          } else if (reason === 'user-modified') {
+            console.log(chalk.yellow(`  ${progress} ! ${relativePath} (modified)`));
+            stats.userModified++;
+          } else {
+            // Unchanged, don't log to reduce noise
+            stats.skipped++;
+          }
+          // Preserve existing hash in manifest
+          if (manifest.files[relativePath]) {
+            newManifest.files[relativePath] = manifest.files[relativePath];
+          }
+          break;
+      }
+    } catch (err) {
+      console.log(chalk.red(`  ${progress} x ${relativePath} (${err.message})`));
+    }
+  }
+
+  // Save manifest
+  saveManifest(projectDir, newManifest);
+
+  // Summary
+  console.log(chalk.cyan('\n  Summary\n'));
+  console.log(`  ${chalk.green('+')} Created:       ${stats.created}`);
+  console.log(`  ${chalk.blue('~')} Updated:       ${stats.updated}`);
+  console.log(`  ${chalk.yellow('!')} Protected:     ${stats.protected}`);
+  console.log(`  ${chalk.yellow('!')} User modified: ${stats.userModified}`);
+  console.log(`  ${chalk.dim('-')} Unchanged:     ${stats.skipped}`);
+
+  console.log(chalk.green(`\n  CSK ${isUpdate ? 'updated' : 'installed'} successfully!\n`));
+
+  // Next steps
+  if (!isUpdate) {
+    console.log(chalk.dim('  Next steps:'));
+    console.log(chalk.dim('  1. Review .claude/ directory'));
+    console.log(chalk.dim('  2. Copy .env.example to .env and configure'));
+    console.log(chalk.dim('  3. Start using CSK commands in Claude Code\n'));
+  }
+}
+
+module.exports = initCommand;

package/src/commands/status.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * Status Command
+ *
+ * Shows CSK installation status in current project.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { loadManifest } = require('../lib/merge');
+const { getToken, getTokenSource } = require('../lib/keychain');
+
+/**
+ * Main status command handler
+ */
+async function statusCommand() {
+  const projectDir = process.cwd();
+
+  console.log(chalk.cyan('\n  CSK Status\n'));
+
+  // Check authentication
+  const token = await getToken();
+  const source = await getTokenSource();
+
+  console.log(chalk.dim('  Authentication:'));
+  if (token) {
+    console.log(chalk.green(`    Authenticated (${formatSource(source)})`));
+  } else {
+    console.log(chalk.red('    Not authenticated'));
+    console.log(chalk.dim('    Run `csk auth --login` to authenticate'));
+  }
+
+  console.log('');
+
+  // Check installation
+  const manifest = loadManifest(projectDir);
+
+  console.log(chalk.dim('  Installation:'));
+  if (manifest.version) {
+    console.log(chalk.green(`    Installed: v${manifest.version}`));
+    console.log(chalk.dim(`    Date: ${manifest.installedAt}`));
+    console.log(chalk.dim(`    Files: ${Object.keys(manifest.files).length}`));
+  } else {
+    console.log(chalk.yellow('    Not installed'));
+    console.log(chalk.dim('    Run `csk init` to install'));
+  }
+
+  console.log('');
+
+  // Check key directories
+  console.log(chalk.dim('  Directories:'));
+
+  const dirs = [
+    { path: '.claude', name: 'Claude Config' },
+    { path: 'core', name: 'Core Rules' },
+    { path: 'domains', name: 'Domains' },
+    { path: 'industries', name: 'Industries' }
+  ];
+
+  for (const dir of dirs) {
+    const fullPath = path.join(projectDir, dir.path);
+    const exists = fs.existsSync(fullPath);
+    const icon = exists ? chalk.green('✓') : chalk.red('✗');
+    console.log(`    ${icon} ${dir.name} (${dir.path}/)`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Format token source for display
+ */
+function formatSource(source) {
+  const sources = {
+    'env': 'env',
+    'gh-cli': 'gh',
+    'keychain': 'keychain',
+    'config': 'config',
+    'none': 'none'
+  };
+  return sources[source] || source;
+}
+
+module.exports = statusCommand;

package/src/commands/update.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Update Command
+ *
+ * Updates the CSK CLI tool itself to latest version.
+ */
+
+const chalk = require('chalk');
+const ora = require('ora');
+const { execSync } = require('child_process');
+const pkg = require('../../package.json');
+
+/**
+ * Main update command handler
+ */
+async function updateCommand() {
+  console.log(chalk.cyan('\n  CSK CLI - Update\n'));
+
+  console.log(chalk.dim(`  Current version: v${pkg.version}\n`));
+
+  const spinner = ora('Checking for updates...').start();
+
+  try {
+    // Get latest version from npm
+    const latestVersion = execSync('npm view csk-cli version', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+
+    if (latestVersion === pkg.version) {
+      spinner.succeed(chalk.green('Already on latest version'));
+      return;
+    }
+
+    spinner.text = `Updating to v${latestVersion}...`;
+
+    // Run npm update
+    execSync('npm install -g csk-cli@latest', {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    spinner.succeed(chalk.green(`Updated to v${latestVersion}`));
+
+    console.log(chalk.dim('\n  Run `csk init` to update project files.\n'));
+  } catch (error) {
+    if (error.message.includes('npm view')) {
+      spinner.fail(chalk.red('Could not check for updates'));
+      console.log(chalk.dim('\n  Package may not be published yet.\n'));
+    } else {
+      spinner.fail(chalk.red('Update failed'));
+      console.log(chalk.dim(`\n  ${error.message}`));
+      console.log(chalk.dim('\n  Try manually: npm install -g csk-cli@latest\n'));
+    }
+  }
+}
+
+module.exports = updateCommand;

package/src/constants.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * CSK CLI Constants
+ * Central configuration for the CLI tool
+ */
+
+const path = require('path');
+const os = require('os');
+
+// Keychain service name for storing GitHub token
+const KEYCHAIN_SERVICE = 'csk-cli';
+const KEYCHAIN_ACCOUNT = 'github-token';
+
+// GitHub repository details
+const GITHUB_OWNER = 'tohaitrieu';
+const GITHUB_REPO = 'content-suite-kit';
+const GITHUB_BRANCH = 'main';
+
+// Local paths
+const CSK_HOME = path.join(os.homedir(), '.csk');
+const CSK_CONFIG_PATH = path.join(CSK_HOME, 'config.json');
+const CSK_CACHE_DIR = path.join(CSK_HOME, 'cache');
+
+// Protected files that should never be overwritten during update
+const PROTECTED_FILES = [
+  '.env',
+  '.env.local',
+  '.env.production',
+  '*.key',
+  '*.pem',
+  'config.local.json',
+  '.csk/config.json'
+];
+
+// Files/directories to exclude from download
+const EXCLUDE_PATTERNS = [
+  '.git',
+  'node_modules',
+  '.DS_Store',
+  '*.log',
+  'packages/csk-cli'  // Don't download CLI itself
+];
+
+// CLI colors
+const COLORS = {
+  success: 'green',
+  error: 'red',
+  warning: 'yellow',
+  info: 'blue',
+  dim: 'gray'
+};
+
+module.exports = {
+  KEYCHAIN_SERVICE,
+  KEYCHAIN_ACCOUNT,
+  GITHUB_OWNER,
+  GITHUB_REPO,
+  GITHUB_BRANCH,
+  CSK_HOME,
+  CSK_CONFIG_PATH,
+  CSK_CACHE_DIR,
+  PROTECTED_FILES,
+  EXCLUDE_PATTERNS,
+  COLORS
+};

package/src/index.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * CSK CLI - Content Suite Kit Command Line Interface
+ *
+ * Downloads and manages CSK skills from private GitHub repository.
+ * Requires GitHub access (granted after purchase).
+ */
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const pkg = require('../package.json');
+
+// Import commands
+const initCommand = require('./commands/init');
+const authCommand = require('./commands/auth');
+const statusCommand = require('./commands/status');
+const updateCommand = require('./commands/update');
+
+const program = new Command();
+
+// ASCII art banner
+const banner = `
+   _____ _____ _  __
+  / ____/ ____| |/ /
+ | |   | (___ | ' /
+ | |    \\___ \\|  <
+ | |___ ____) | . \\
+  \\____|_____/|_|\\_\\
+
+  Content Suite Kit CLI v${pkg.version}
+`;
+
+program
+  .name('csk')
+  .description('Content Suite Kit CLI - Download and manage CSK skills')
+  .version(pkg.version)
+  .addHelpText('before', chalk.cyan(banner));
+
+// Init command - download/update CSK in current project
+program
+  .command('init')
+  .description('Initialize or update CSK in current project')
+  .option('-f, --force', 'Force overwrite existing files')
+  .option('--no-merge', 'Skip smart merge, overwrite all')
+  .action(initCommand);
+
+// Auth command - manage GitHub authentication
+program
+  .command('auth')
+  .description('Manage GitHub authentication')
+  .option('--login', 'Add or update GitHub token')
+  .option('--logout', 'Remove stored GitHub token')
+  .option('--status', 'Check authentication status')
+  .action(authCommand);
+
+// Status command - check installation status
+program
+  .command('status')
+  .description('Check CSK installation status')
+  .action(statusCommand);
+
+// Update command - update CLI tool itself
+program
+  .command('update')
+  .description('Update CSK CLI to latest version')
+  .action(updateCommand);
+
+// Parse arguments
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/src/lib/github.js

@@ -0,0 +1,186 @@
+'use strict';
+
+/**
+ * GitHub API Client
+ *
+ * Handles authentication and repository operations.
+ */
+
+const https = require('https');
+const { GITHUB_OWNER, GITHUB_REPO, GITHUB_BRANCH } = require('../constants');
+
+/**
+ * Make authenticated GitHub API request
+ * @param {string} token - GitHub PAT
+ * @param {string} endpoint - API endpoint (without base URL)
+ * @returns {Promise<Object>}
+ */
+async function apiRequest(token, endpoint) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'api.github.com',
+      path: endpoint,
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': 'csk-cli',
+        'X-GitHub-Api-Version': '2022-11-28'
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          resolve(JSON.parse(data));
+        } else if (res.statusCode === 401) {
+          reject(new Error('Authentication failed. Please check your GitHub token.'));
+        } else if (res.statusCode === 403) {
+          reject(new Error('Access denied. You may not have access to this repository.'));
+        } else if (res.statusCode === 404) {
+          reject(new Error('Repository not found. Please verify your access.'));
+        } else {
+          reject(new Error(`GitHub API error: ${res.statusCode}`));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * Verify token has access to the CSK repository
+ * @param {string} token - GitHub PAT
+ * @returns {Promise<{valid: boolean, error?: string}>}
+ */
+async function verifyAccess(token) {
+  try {
+    await apiRequest(token, `/repos/${GITHUB_OWNER}/${GITHUB_REPO}`);
+    return { valid: true };
+  } catch (error) {
+    return { valid: false, error: error.message };
+  }
+}
+
+/**
+ * Get repository tree (file listing)
+ * @param {string} token - GitHub PAT
+ * @param {string} branch - Branch name
+ * @returns {Promise<Array>}
+ */
+async function getRepoTree(token, branch = GITHUB_BRANCH) {
+  const data = await apiRequest(
+    token,
+    `/repos/${GITHUB_OWNER}/${GITHUB_REPO}/git/trees/${branch}?recursive=1`
+  );
+  return data.tree || [];
+}
+
+/**
+ * Get file content from repository
+ * @param {string} token - GitHub PAT
+ * @param {string} filePath - Path to file in repo
+ * @returns {Promise<string>}
+ */
+async function getFileContent(token, filePath) {
+  const data = await apiRequest(
+    token,
+    `/repos/${GITHUB_OWNER}/${GITHUB_REPO}/contents/${filePath}?ref=${GITHUB_BRANCH}`
+  );
+
+  if (data.encoding === 'base64') {
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  }
+
+  return data.content;
+}
+
+/**
+ * Download file as binary
+ * @param {string} token - GitHub PAT
+ * @param {string} filePath - Path to file in repo
+ * @returns {Promise<Buffer>}
+ */
+async function downloadFile(token, filePath) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'raw.githubusercontent.com',
+      path: `/${GITHUB_OWNER}/${GITHUB_REPO}/${GITHUB_BRANCH}/${filePath}`,
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'User-Agent': 'csk-cli'
+      }
+    };
+
+    const req = https.request(options, (res) => {
+      if (res.statusCode === 302 || res.statusCode === 301) {
+        // Follow redirect
+        const redirectUrl = new URL(res.headers.location);
+        const redirectOptions = {
+          hostname: redirectUrl.hostname,
+          path: redirectUrl.pathname + redirectUrl.search,
+          method: 'GET',
+          headers: {
+            'User-Agent': 'csk-cli'
+          }
+        };
+
+        const redirectReq = https.request(redirectOptions, (redirectRes) => {
+          const chunks = [];
+          redirectRes.on('data', chunk => chunks.push(chunk));
+          redirectRes.on('end', () => resolve(Buffer.concat(chunks)));
+        });
+        redirectReq.on('error', reject);
+        redirectReq.end();
+        return;
+      }
+
+      if (res.statusCode !== 200) {
+        reject(new Error(`Failed to download file: ${res.statusCode}`));
+        return;
+      }
+
+      const chunks = [];
+      res.on('data', chunk => chunks.push(chunk));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * Get latest release version
+ * @param {string} token - GitHub PAT
+ * @returns {Promise<{tag: string, name: string, published: string}>}
+ */
+async function getLatestRelease(token) {
+  try {
+    const data = await apiRequest(
+      token,
+      `/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/latest`
+    );
+    return {
+      tag: data.tag_name,
+      name: data.name,
+      published: data.published_at
+    };
+  } catch (error) {
+    // No releases, use branch
+    return null;
+  }
+}
+
+module.exports = {
+  verifyAccess,
+  getRepoTree,
+  getFileContent,
+  downloadFile,
+  getLatestRelease
+};

package/src/lib/keychain.js

@@ -0,0 +1,208 @@
+'use strict';
+
+/**
+ * Keychain Manager
+ *
+ * Securely stores GitHub token in OS keychain:
+ * - macOS: Keychain Access
+ * - Windows: Credential Manager
+ * - Linux: libsecret (GNOME Keyring)
+ *
+ * Falls back to config file if keychain unavailable.
+ */
+
+const keytar = require('keytar');
+const fs = require('fs');
+const path = require('path');
+const { KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, CSK_HOME, CSK_CONFIG_PATH } = require('../constants');
+
+/**
+ * Check if keytar (native keychain) is available
+ */
+async function isKeychainAvailable() {
+  try {
+    // Try a simple operation to check if keytar works
+    await keytar.findCredentials(KEYCHAIN_SERVICE);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Store GitHub token securely
+ * @param {string} token - GitHub Personal Access Token
+ * @returns {Promise<{success: boolean, method: string}>}
+ */
+async function storeToken(token) {
+  // Try keychain first
+  if (await isKeychainAvailable()) {
+    try {
+      await keytar.setPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, token);
+      return { success: true, method: 'keychain' };
+    } catch (error) {
+      // Fall through to config file
+    }
+  }
+
+  // Fallback to config file (less secure)
+  try {
+    ensureConfigDir();
+    const config = loadConfig();
+    config.github_token = token;
+    saveConfig(config);
+    return { success: true, method: 'config' };
+  } catch (error) {
+    return { success: false, method: 'none', error: error.message };
+  }
+}
+
+/**
+ * Retrieve GitHub token
+ * @returns {Promise<string|null>}
+ */
+async function getToken() {
+  // Priority 1: Environment variable
+  if (process.env.GITHUB_TOKEN) {
+    return process.env.GITHUB_TOKEN;
+  }
+  if (process.env.GH_TOKEN) {
+    return process.env.GH_TOKEN;
+  }
+
+  // Priority 2: GitHub CLI token
+  try {
+    const { execSync } = require('child_process');
+    const ghToken = execSync('gh auth token', { encoding: 'utf-8' }).trim();
+    if (ghToken) {
+      return ghToken;
+    }
+  } catch (error) {
+    // gh CLI not available or not logged in
+  }
+
+  // Priority 3: OS Keychain
+  if (await isKeychainAvailable()) {
+    try {
+      const token = await keytar.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+      if (token) {
+        return token;
+      }
+    } catch (error) {
+      // Keychain error, try config file
+    }
+  }
+
+  // Priority 4: Config file
+  try {
+    const config = loadConfig();
+    if (config.github_token) {
+      return config.github_token;
+    }
+  } catch (error) {
+    // No config file
+  }
+
+  return null;
+}
+
+/**
+ * Delete stored GitHub token
+ * @returns {Promise<boolean>}
+ */
+async function deleteToken() {
+  let deleted = false;
+
+  // Delete from keychain
+  if (await isKeychainAvailable()) {
+    try {
+      await keytar.deletePassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+      deleted = true;
+    } catch (error) {
+      // Ignore
+    }
+  }
+
+  // Delete from config
+  try {
+    const config = loadConfig();
+    if (config.github_token) {
+      delete config.github_token;
+      saveConfig(config);
+      deleted = true;
+    }
+  } catch (error) {
+    // Ignore
+  }
+
+  return deleted;
+}
+
+/**
+ * Get token storage method currently in use
+ * @returns {Promise<string>} 'env', 'gh-cli', 'keychain', 'config', or 'none'
+ */
+async function getTokenSource() {
+  if (process.env.GITHUB_TOKEN || process.env.GH_TOKEN) {
+    return 'env';
+  }
+
+  try {
+    const { execSync } = require('child_process');
+    const ghToken = execSync('gh auth token', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (ghToken) {
+      return 'gh-cli';
+    }
+  } catch (error) {
+    // gh CLI not available
+  }
+
+  if (await isKeychainAvailable()) {
+    try {
+      const token = await keytar.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+      if (token) {
+        return 'keychain';
+      }
+    } catch (error) {
+      // Keychain error
+    }
+  }
+
+  try {
+    const config = loadConfig();
+    if (config.github_token) {
+      return 'config';
+    }
+  } catch (error) {
+    // No config
+  }
+
+  return 'none';
+}
+
+// Helper functions for config file
+function ensureConfigDir() {
+  if (!fs.existsSync(CSK_HOME)) {
+    fs.mkdirSync(CSK_HOME, { recursive: true });
+  }
+}
+
+function loadConfig() {
+  if (fs.existsSync(CSK_CONFIG_PATH)) {
+    return JSON.parse(fs.readFileSync(CSK_CONFIG_PATH, 'utf-8'));
+  }
+  return {};
+}
+
+function saveConfig(config) {
+  ensureConfigDir();
+  fs.writeFileSync(CSK_CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+module.exports = {
+  storeToken,
+  getToken,
+  deleteToken,
+  getTokenSource,
+  isKeychainAvailable
+};

package/src/lib/merge.js

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * Smart Merge Logic
+ *
+ * Handles intelligent file merging during updates:
+ * - Protects user-modified files
+ * - Never overwrites sensitive files (.env, *.key)
+ * - Preserves custom configurations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { PROTECTED_FILES, EXCLUDE_PATTERNS } = require('../constants');
+
+/**
+ * Check if file matches protected patterns
+ * @param {string} filePath - Relative file path
+ * @returns {boolean}
+ */
+function isProtected(filePath) {
+  const fileName = path.basename(filePath);
+
+  for (const pattern of PROTECTED_FILES) {
+    if (pattern.includes('*')) {
+      // Wildcard pattern
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      if (regex.test(fileName)) {
+        return true;
+      }
+    } else {
+      // Exact match or path ends with pattern
+      if (fileName === pattern || filePath.endsWith(pattern)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if file/directory should be excluded
+ * @param {string} filePath - Relative file path
+ * @returns {boolean}
+ */
+function shouldExclude(filePath) {
+  const parts = filePath.split('/');
+
+  for (const pattern of EXCLUDE_PATTERNS) {
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      if (parts.some(part => regex.test(part))) {
+        return true;
+      }
+    } else {
+      if (parts.includes(pattern)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Calculate file hash for change detection
+ * @param {string} filePath - Absolute file path
+ * @returns {string|null}
+ */
+function getFileHash(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('md5').update(content).digest('hex');
+}
+
+/**
+ * Determine merge action for a file
+ * @param {string} targetPath - Absolute path in target directory
+ * @param {string} relativePath - Relative path in repo
+ * @param {Buffer} newContent - New content from repo
+ * @param {Object} manifest - Previous installation manifest
+ * @returns {{action: string, reason: string}}
+ */
+function determineMergeAction(targetPath, relativePath, newContent, manifest = {}) {
+  // Check if protected
+  if (isProtected(relativePath)) {
+    return { action: 'skip', reason: 'protected' };
+  }
+
+  // Check if file exists
+  if (!fs.existsSync(targetPath)) {
+    return { action: 'create', reason: 'new' };
+  }
+
+  // Calculate hashes
+  const currentHash = getFileHash(targetPath);
+  const newHash = crypto.createHash('md5').update(newContent).digest('hex');
+  const originalHash = manifest[relativePath];
+
+  // Same content, skip
+  if (currentHash === newHash) {
+    return { action: 'skip', reason: 'unchanged' };
+  }
+
+  // Check if user modified the file
+  if (originalHash && currentHash !== originalHash) {
+    // User modified, don't overwrite
+    return { action: 'skip', reason: 'user-modified' };
+  }
+
+  // File changed in repo but user didn't modify
+  return { action: 'update', reason: 'repo-updated' };
+}
+
+/**
+ * Load installation manifest
+ * @param {string} projectDir - Project directory
+ * @returns {Object}
+ */
+function loadManifest(projectDir) {
+  const manifestPath = path.join(projectDir, '.csk', 'manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  }
+  return { files: {}, version: null, installedAt: null };
+}
+
+/**
+ * Save installation manifest
+ * @param {string} projectDir - Project directory
+ * @param {Object} manifest - Manifest data
+ */
+function saveManifest(projectDir, manifest) {
+  const cskDir = path.join(projectDir, '.csk');
+  if (!fs.existsSync(cskDir)) {
+    fs.mkdirSync(cskDir, { recursive: true });
+  }
+
+  const manifestPath = path.join(cskDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Create directory recursively
+ * @param {string} dirPath - Directory path
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+module.exports = {
+  isProtected,
+  shouldExclude,
+  getFileHash,
+  determineMergeAction,
+  loadManifest,
+  saveManifest,
+  ensureDir
+};