claude-code-pack 1.0.0 → 1.0.1

package/README.md

@@ -2,19 +2,36 @@
 
 Portable Claude Code setup — installs your plugins, skills, MCP servers, and settings on any machine with a single command.
 
-## Quick Start
+## Installation
+
+### From npm
 
 ```bash
-npx claude-pack install
+npx claude-code-pack install
 ```
 
 Or install globally:
 
 ```bash
-npm install -g claude-pack
+npm install -g claude-code-pack
+claude-pack install
+```
+
+### From GitHub
+
+```bash
+git clone git@github.com:lvtan71/claude-pack.git
+cd claude-pack
+npm link
 claude-pack install
 ```
 
+Or run directly without installing:
+
+```bash
+npx github:lvtan71/claude-pack install
+```
+
 ## What It Does
 
 `claude-pack` reads `claude-pack.config.json` and sets up your Claude Code environment:
@@ -28,43 +45,51 @@ claude-pack install
 
 Everything is fetched fresh from GitHub, so you always get the latest version.
 
-## Configuration
+## What's Included
 
-Edit `claude-pack.config.json` to customize your setup:
+### Plugins
 
-```json
-{
-  "plugins": [
-    {
-      "name": "claude-mem",
-      "marketplace": "thedotmack",
-      "repo": "thedotmack/claude-mem",
-      "enabled": true
-    }
-  ],
-  "marketplaces": [
-    { "name": "thedotmack", "repo": "thedotmack/claude-mem" }
-  ],
-  "skills": [
-    { "name": "my-skill", "source": "bundled" },
-    { "name": "remote-skill", "source": "github", "repo": "user/repo" }
-  ],
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["-y", "@some/mcp-server"]
-    }
-  },
-  "settings": {
-    "model": "opus"
-  }
-}
-```
+| Plugin | Source | Description |
+|--------|--------|-------------|
+| **claude-mem** | [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) | Persistent cross-session memory, smart code exploration (AST-based), phased implementation plans, and timeline reports |
+| **understand-anything** | [Lum1104/Understand-Anything](https://github.com/Lum1104/Understand-Anything) | Codebase analysis, interactive knowledge graphs, architecture visualization, onboarding guides, and diff analysis |
 
-### Skill Sources
+### Marketplaces
 
-- `"source": "bundled"` — copies from the `skills/` directory in this package
-- `"source": "github", "repo": "user/repo"` — clones from GitHub
+| Marketplace | Source | Description |
+|-------------|--------|-------------|
+| **thedotmack** | [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) | Plugin marketplace for claude-mem and related tools |
+| **understand-anything** | [Lum1104/Understand-Anything](https://github.com/Lum1104/Understand-Anything) | Codebase understanding, onboarding, and architecture analysis tools |
+
+### Skills (Bundled)
+
+| Skill | Description |
+|-------|-------------|
+| **cloud-devops** | Cloud infrastructure and DevOps workflows — AWS, Azure, GCP, Kubernetes, Terraform, CI/CD, monitoring |
+| **fastapi** | FastAPI best practices, Pydantic models, dependency injection, streaming, and latest patterns |
+| **senior-ml-engineer** | MLOps pipelines, model deployment, drift monitoring, RAG systems, LLM integration, cost optimization |
+| **technical-writer** | Documentation, API references, guides, tutorials, and technical content creation |
+
+### MCP Servers
+
+| Server | Type | Source | Description |
+|--------|------|--------|-------------|
+| **linear** | HTTP | [mcp.linear.app](https://mcp.linear.app/mcp) | Linear project management — issues, projects, comments, milestones |
+| **context7** | HTTP | [mcp.context7.com](https://mcp.context7.com/mcp) | Up-to-date library documentation and code examples |
+| **fetch** | stdio | `mcp-server-fetch` (uvx) | Fetch web content for processing |
+| **filesystem** | stdio | `@modelcontextprotocol/server-filesystem` (npx) | File system access (defaults to `$HOME`, configurable at install) |
+| **sequential-thinking** | stdio | `@modelcontextprotocol/server-sequential-thinking` (npx) | Step-by-step reasoning and problem decomposition |
+| **time** | stdio | `mcp-server-time` (uvx) | Current time and timezone operations |
+
+> `$HOME` in MCP server args is automatically resolved to the user's home directory at install time.
+> The **filesystem** server prompts you during install to confirm or customize the path. Works on Linux/WSL, macOS, and Windows.
+
+### Settings
+
+| Setting | Value |
+|---------|-------|
+| **Model** | `opus` |
+| **Statusline** | Custom bash script with context window, 5h/7d rate limit bars, and color-coded usage indicators |
 
 ## Commands
 
@@ -81,29 +106,62 @@ claude-pack install --skip-settings # Skip settings merge
 claude-pack install --dry-run       # Preview without changes
 ```
 
-## Adding New Components
+## Contributing
 
-### Add a plugin
+### Setup
 
-1. Add to `claude-pack.config.json` under `plugins` and `marketplaces`
-2. Run `claude-pack install`
+```bash
+git clone git@github.com:lvtan71/claude-pack.git
+cd claude-pack
+npm link    # makes `claude-pack` command available locally
+```
+
+### Adding a Plugin
 
-### Add a skill from GitHub
+1. Edit `claude-pack.config.json` — add entries to both `plugins` and `marketplaces`:
 
 ```json
+// In "plugins" array:
 {
-  "name": "my-skill",
-  "source": "github",
-  "repo": "username/my-skill-repo"
+  "name": "my-plugin",
+  "marketplace": "marketplace-name",
+  "repo": "github-user/repo-name",
+  "enabled": true
+}
+
+// In "marketplaces" array:
+{
+  "name": "marketplace-name",
+  "repo": "github-user/repo-name"
 }
 ```
 
-### Add a bundled skill
+2. Update the **Plugins** and **Marketplaces** tables in this README.
+
+### Adding a Skill
 
-1. Create `skills/my-skill/SKILL.md`
-2. Add to config: `{ "name": "my-skill", "source": "bundled" }`
+**Option A — Bundled skill** (skill files live in this repo):
 
-### Add an MCP server
+1. Create `skills/my-skill/SKILL.md` (and optional `references/` directory).
+2. Add to `claude-pack.config.json`:
+
+```json
+{ "name": "my-skill", "source": "bundled" }
+```
+
+**Option B — GitHub-hosted skill** (cloned at install time):
+
+1. Add to `claude-pack.config.json`:
+
+```json
+{ "name": "my-skill", "source": "github", "repo": "github-user/my-skill-repo" }
+```
+
+2. Update the **Skills** table in this README.
+
+### Adding an MCP Server
+
+1. Add to the `mcpServers` object in `claude-pack.config.json`:
 
 ```json
 "mcpServers": {
@@ -114,7 +172,46 @@ claude-pack install --dry-run       # Preview without changes
 }
 ```
 
+2. Update the **MCP Servers** section in this README.
+
+### Publishing a New Version
+
+1. Make your changes and commit.
+2. Bump the version:
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1 (bug fixes, small updates)
+npm version minor   # 1.0.0 → 1.1.0 (new plugins/skills added)
+npm version major   # 1.0.0 → 2.0.0 (breaking config changes)
+```
+
+3. Push with tags:
+
+```bash
+git push origin main --tags
+```
+
+4. Publish to npm:
+
+```bash
+npm publish
+```
+
+> `npm version` automatically creates a git commit and tag (e.g., `v1.1.0`).
+> Make sure all changes are committed before running it.
+
+### Pull Request Guidelines
+
+- One plugin/skill/MCP server per PR when possible.
+- Update the README tables to reflect your additions.
+- Test with `claude-pack install --dry-run` before submitting.
+- Test a full install with `claude-pack install --force` on a clean environment if possible.
+
 ## Requirements
 
 - Node.js >= 18
 - git
+
+## License
+
+MIT

package/claude-pack.config.json

@@ -5,6 +5,12 @@
       "marketplace": "thedotmack",
       "repo": "thedotmack/claude-mem",
       "enabled": true
+    },
+    {
+      "name": "understand-anything",
+      "marketplace": "understand-anything",
+      "repo": "Lum1104/Understand-Anything",
+      "enabled": true
     }
   ],
   "marketplaces": [
@@ -18,12 +24,60 @@
     }
   ],
   "skills": [
-    { "name": "cloud-devops", "source": "bundled" },
-    { "name": "fastapi", "source": "bundled" },
-    { "name": "senior-ml-engineer", "source": "bundled" },
-    { "name": "technical-writer", "source": "bundled" }
+    {
+      "name": "cloud-devops",
+      "source": "bundled"
+    },
+    {
+      "name": "fastapi",
+      "source": "bundled"
+    },
+    {
+      "name": "senior-ml-engineer",
+      "source": "bundled"
+    },
+    {
+      "name": "technical-writer",
+      "source": "bundled"
+    }
   ],
-  "mcpServers": {},
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.linear.app/mcp"
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    },
+    "fetch": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-fetch"
+      ]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "$HOME"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "time": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-time"
+      ]
+    }
+  },
   "settings": {
     "model": "opus",
     "statusLine": {
@@ -34,4 +88,4 @@
   "assets": {
     "statusline": "assets/statusline-command.sh"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-pack",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Portable Claude Code setup — installs plugins, skills, MCP servers, and statusline on any machine",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tanle/claude-pack.git"
+    "url": "git+https://github.com/lvtan71/claude-pack.git"
   },
   "engines": {
     "node": ">=18"

package/src/install.mjs

@@ -1,8 +1,9 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACK_ROOT = resolve(__dirname, '..');
@@ -37,6 +38,37 @@ function writeJSON(path, data) {
   writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
 }
 
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function getDefaultHome() {
+  return homedir();
+}
+
+function resolveHomeInConfig(obj) {
+  if (typeof obj === 'string') {
+    return obj.replace(/\$HOME/g, homedir());
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(resolveHomeInConfig);
+  }
+  if (obj && typeof obj === 'object') {
+    const resolved = {};
+    for (const [k, v] of Object.entries(obj)) {
+      resolved[k] = resolveHomeInConfig(v);
+    }
+    return resolved;
+  }
+  return obj;
+}
+
 function loadConfig() {
   const configPath = join(PACK_ROOT, 'claude-pack.config.json');
   return JSON.parse(readFileSync(configPath, 'utf8'));
@@ -59,7 +91,7 @@ function gitClone(repo, dest) {
   return 'cloned';
 }
 
-function getPluginVersion(marketplaceDir, pluginName) {
+function getPluginVersion(marketplaceDir) {
   // Try to read version from plugin's package.json or manifest
   const candidates = [
     join(marketplaceDir, 'plugin', 'package.json'),
@@ -82,7 +114,7 @@ function getGitCommitSha(dir) {
   }
 }
 
-function findPluginInstallPath(marketplaceDir, pluginName) {
+function findPluginInstallPath(marketplaceDir) {
   // Look for a plugin/ subdirectory or the root
   const pluginSubdir = join(marketplaceDir, 'plugin');
   if (existsSync(pluginSubdir)) return pluginSubdir;
@@ -288,7 +320,7 @@ function installSkills(config, flags) {
 
 // ─── Settings Merge ────────────────────────────────────────────────────
 
-function installSettings(config, flags) {
+async function installSettings(config, flags) {
   console.log('\n⚙  Settings');
 
   const settings = readJSON(SETTINGS_PATH);
@@ -330,17 +362,52 @@ function installSettings(config, flags) {
 
   // Merge MCP servers
   if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
+    console.log('\n🔌 MCP Servers');
     if (!settings.mcpServers) settings.mcpServers = {};
+
+    // Resolve filesystem server path interactively
+    const home = getDefaultHome();
+    const os = platform();
+    const osLabel = os === 'win32' ? 'Windows' : os === 'darwin' ? 'macOS' : 'Linux/WSL';
+
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+      if (name === 'filesystem' && !flags.dryRun) {
+        console.log(`\n  Detected OS: ${osLabel}`);
+        console.log(`  Default filesystem path: ${home}`);
+        const answer = await prompt(`  Use "${home}" as filesystem root? [Y/n/custom path] `);
+
+        if (answer === '' || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+          const resolved = JSON.parse(JSON.stringify(serverConfig));
+          resolved.args = resolved.args.map((a) => a === '$HOME' ? home : a);
+          settings.mcpServers[name] = resolved;
+          log('✓', `MCP server "${name}" configured (${home})`);
+        } else if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+          log('⊘', `MCP server "${name}" skipped — configure manually in ~/.claude/settings.json:`);
+          console.log(`      "mcpServers": {`);
+          console.log(`        "filesystem": {`);
+          console.log(`          "command": "npx",`);
+          console.log(`          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]`);
+          console.log(`        }`);
+          console.log(`      }`);
+        } else {
+          // User provided a custom path
+          const customPath = answer.replace(/^~/, home);
+          const resolved = JSON.parse(JSON.stringify(serverConfig));
+          resolved.args = resolved.args.map((a) => a === '$HOME' ? customPath : a);
+          settings.mcpServers[name] = resolved;
+          log('✓', `MCP server "${name}" configured (${customPath})`);
+        }
+        continue;
+      }
+
+      const resolved = resolveHomeInConfig(serverConfig);
       if (flags.dryRun) {
         log('○', `Would configure MCP server "${name}"`);
       } else {
-        settings.mcpServers[name] = serverConfig;
+        settings.mcpServers[name] = resolved;
         log('✓', `MCP server "${name}" configured`);
       }
     }
-  } else {
-    log('●', 'No MCP servers to configure (they come from plugins)');
   }
 
   if (!flags.dryRun) {
@@ -379,7 +446,7 @@ export async function install(flags = {}) {
 
   if (!flags.skipPlugins) installPlugins(config, flags);
   if (!flags.skipSkills) installSkills(config, flags);
-  if (!flags.skipSettings) installSettings(config, flags);
+  if (!flags.skipSettings) await installSettings(config, flags);
 
   console.log('\n────────────────────────────────────────────');
   if (flags.dryRun) {