bitcompass 0.3.2 → 0.3.4

package/dist/commands/rules.d.ts

@@ -2,5 +2,6 @@ export declare const runRulesSearch: (query?: string) => Promise<void>;
 export declare const runRulesList: () => Promise<void>;
 export declare const runRulesPull: (id?: string, options?: {
     global?: boolean;
+    copy?: boolean;
 }) => Promise<void>;
 export declare const runRulesPush: (file?: string) => Promise<void>;

package/dist/commands/rules.js

@@ -1,13 +1,9 @@
 import inquirer from 'inquirer';
 import ora from 'ora';
 import chalk from 'chalk';
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
 import { loadCredentials } from '../auth/config.js';
-import { getProjectConfig } from '../auth/project-config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
-import { ruleFilename } from '../lib/slug.js';
+import { pullRuleToFile } from '../lib/rule-file-ops.js';
 export const runRulesSearch = async (query) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
@@ -66,28 +62,28 @@ export const runRulesPull = async (id, options) => {
         ]);
         targetId = choice.id;
     }
-    const rule = await getRuleById(targetId);
-    if (!rule) {
-        console.error(chalk.red('Rule not found.'));
-        process.exit(1);
-    }
-    let outDir;
-    if (options?.global) {
-        // Use global location: ~/.cursor/rules/
-        outDir = join(homedir(), '.cursor', 'rules');
-    }
-    else {
-        // Use project config (default behavior)
-        const { outputPath } = getProjectConfig({ warnIfMissing: true });
-        outDir = join(process.cwd(), outputPath);
+    const spinner = ora('Pulling rule…').start();
+    try {
+        const filename = await pullRuleToFile(targetId, {
+            global: options?.global,
+            useSymlink: !options?.copy, // Use symlink unless --copy flag is set
+        });
+        spinner.succeed(chalk.green('Pulled rule'));
+        console.log(chalk.dim(filename));
+        if (options?.copy) {
+            console.log(chalk.dim('Copied as file (not a symlink)'));
+        }
+        else {
+            console.log(chalk.dim('Created symbolic link to cached rule'));
+        }
+        if (options?.global) {
+            console.log(chalk.dim('Installed globally for all projects'));
+        }
     }
-    mkdirSync(outDir, { recursive: true });
-    const filename = join(outDir, ruleFilename(rule.title, rule.id));
-    const content = `# ${rule.title}\n\n${rule.description}\n\n${rule.body}\n`;
-    writeFileSync(filename, content);
-    console.log(chalk.green('Wrote'), filename);
-    if (options?.global) {
-        console.log(chalk.dim('Installed globally for all projects'));
+    catch (error) {
+        spinner.fail(chalk.red('Failed to pull rule'));
+        console.error(chalk.red(error.message));
+        process.exit(1);
     }
 };
 export const runRulesPush = async (file) => {

package/dist/commands/solutions.d.ts

@@ -1,5 +1,6 @@
 export declare const runSolutionsSearch: (query?: string) => Promise<void>;
 export declare const runSolutionsPull: (id?: string, options?: {
     global?: boolean;
+    copy?: boolean;
 }) => Promise<void>;
 export declare const runSolutionsPush: (file?: string) => Promise<void>;

package/dist/commands/solutions.js

@@ -1,13 +1,9 @@
 import inquirer from 'inquirer';
 import ora from 'ora';
 import chalk from 'chalk';
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
 import { loadCredentials } from '../auth/config.js';
-import { getProjectConfig } from '../auth/project-config.js';
 import { searchRules, fetchRules, getRuleById, insertRule } from '../api/client.js';
-import { solutionFilename } from '../lib/slug.js';
+import { pullRuleToFile } from '../lib/rule-file-ops.js';
 export const runSolutionsSearch = async (query) => {
     if (!loadCredentials()) {
         console.error(chalk.red('Not logged in. Run bitcompass login.'));
@@ -54,28 +50,28 @@ export const runSolutionsPull = async (id, options) => {
         ]);
         targetId = choice.id;
     }
-    const rule = await getRuleById(targetId);
-    if (!rule) {
-        console.error(chalk.red('Solution not found.'));
-        process.exit(1);
-    }
-    let outDir;
-    if (options?.global) {
-        // Use global location: ~/.cursor/rules/
-        outDir = join(homedir(), '.cursor', 'rules');
-    }
-    else {
-        // Use project config (default behavior)
-        const { outputPath } = getProjectConfig({ warnIfMissing: true });
-        outDir = join(process.cwd(), outputPath);
+    const spinner = ora('Pulling solution…').start();
+    try {
+        const filename = await pullRuleToFile(targetId, {
+            global: options?.global,
+            useSymlink: !options?.copy, // Use symlink unless --copy flag is set
+        });
+        spinner.succeed(chalk.green('Pulled solution'));
+        console.log(chalk.dim(filename));
+        if (options?.copy) {
+            console.log(chalk.dim('Copied as file (not a symlink)'));
+        }
+        else {
+            console.log(chalk.dim('Created symbolic link to cached solution'));
+        }
+        if (options?.global) {
+            console.log(chalk.dim('Installed globally for all projects'));
+        }
     }
-    mkdirSync(outDir, { recursive: true });
-    const filename = join(outDir, solutionFilename(rule.title, rule.id));
-    const content = `# ${rule.title}\n\n${rule.description}\n\n## Solution\n\n${rule.body}\n`;
-    writeFileSync(filename, content);
-    console.log(chalk.green('Wrote'), filename);
-    if (options?.global) {
-        console.log(chalk.dim('Installed globally for all projects'));
+    catch (error) {
+        spinner.fail(chalk.red('Failed to pull solution'));
+        console.error(chalk.red(error.message));
+        process.exit(1);
     }
 };
 export const runSolutionsPush = async (file) => {

package/dist/index.js

@@ -55,8 +55,9 @@ rules.command('search [query]').description('Search rules').action((query) => ru
 rules.command('list').description('List rules').action(() => runRulesList().catch(handleErr));
 rules
     .command('pull [id]')
-    .description('Pull a rule by ID or choose from list')
+    .description('Pull a rule by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
+    .option('--copy', 'Copy file instead of creating symbolic link')
     .action((id, options) => runRulesPull(id, options).catch(handleErr));
 rules.command('push [file]').description('Push a rule (file or interactive)').action((file) => runRulesPush(file).catch(handleErr));
 // solutions
@@ -64,8 +65,9 @@ const solutions = program.command('solutions').description('Manage solutions');
 solutions.command('search [query]').description('Search solutions').action((query) => runSolutionsSearch(query).catch(handleErr));
 solutions
     .command('pull [id]')
-    .description('Pull a solution by ID or choose from list')
+    .description('Pull a solution by ID or choose from list (creates symbolic link by default)')
     .option('-g, --global', 'Install globally to ~/.cursor/rules/ for all projects')
+    .option('--copy', 'Copy file instead of creating symbolic link')
     .action((id, options) => runSolutionsPull(id, options).catch(handleErr));
 solutions.command('push [file]').description('Push a solution (file or interactive)').action((file) => runSolutionsPush(file).catch(handleErr));
 // mcp

package/dist/lib/git-analysis.d.ts

@@ -2,7 +2,7 @@ export type TimeFrame = 'day' | 'week' | 'month';
 export interface RepoSummary {
     remote_url: string;
     branch: string;
-    repo_path: string;
+    repo_path?: string;
 }
 export interface GitCommitInfo {
     hash: string;
@@ -28,7 +28,8 @@ export interface PeriodBounds {
  */
 export declare const getRepoRoot: (cwd: string) => string | null;
 /**
- * Get a short summary of the repo: remote URL, current branch, path.
+ * Get a short summary of the repo: remote URL, current branch.
+ * Note: repo_path is no longer included to avoid storing absolute paths.
  */
 export declare const getRepoSummary: (repoRoot: string) => RepoSummary;
 /**

package/dist/lib/git-analysis.js

@@ -24,7 +24,8 @@ export const getRepoRoot = (cwd) => {
     }
 };
 /**
- * Get a short summary of the repo: remote URL, current branch, path.
+ * Get a short summary of the repo: remote URL, current branch.
+ * Note: repo_path is no longer included to avoid storing absolute paths.
  */
 export const getRepoSummary = (repoRoot) => {
     const remoteUrl = exec('git remote get-url origin', repoRoot) || '';
@@ -32,7 +33,6 @@ export const getRepoSummary = (repoRoot) => {
     return {
         remote_url: remoteUrl,
         branch,
-        repo_path: repoRoot,
     };
 };
 /**

package/dist/lib/rule-cache.d.ts

@@ -0,0 +1,14 @@
+import type { Rule } from '../types.js';
+/**
+ * Gets the cache directory for rules (~/.bitcompass/cache/rules/)
+ */
+export declare const getCacheDir: () => string;
+/**
+ * Gets the cached file path for a rule by ID
+ */
+export declare const getCachedRulePath: (rule: Rule) => string;
+/**
+ * Ensures a rule is cached. Downloads and caches it if not present or outdated.
+ * Returns the path to the cached file.
+ */
+export declare const ensureRuleCached: (id: string) => Promise<string>;

package/dist/lib/rule-cache.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, writeFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir } from '../auth/config.js';
+import { getRuleById } from '../api/client.js';
+import { ruleFilename, solutionFilename } from './slug.js';
+/**
+ * Gets the cache directory for rules (~/.bitcompass/cache/rules/)
+ */
+export const getCacheDir = () => {
+    const cacheDir = join(getConfigDir(), 'cache', 'rules');
+    if (!existsSync(cacheDir)) {
+        mkdirSync(cacheDir, { mode: 0o755, recursive: true });
+    }
+    return cacheDir;
+};
+/**
+ * Gets the cached file path for a rule by ID
+ */
+export const getCachedRulePath = (rule) => {
+    const cacheDir = getCacheDir();
+    const filename = rule.kind === 'solution'
+        ? solutionFilename(rule.title, rule.id)
+        : ruleFilename(rule.title, rule.id);
+    return join(cacheDir, `${rule.id}-${filename}`);
+};
+/**
+ * Ensures a rule is cached. Downloads and caches it if not present or outdated.
+ * Returns the path to the cached file.
+ */
+export const ensureRuleCached = async (id) => {
+    const rule = await getRuleById(id);
+    if (!rule) {
+        throw new Error(`Rule or solution with ID ${id} not found.`);
+    }
+    const cachedPath = getCachedRulePath(rule);
+    const needsUpdate = !existsSync(cachedPath) || isCacheOutdated(cachedPath, rule);
+    if (needsUpdate) {
+        const content = rule.kind === 'solution'
+            ? `# ${rule.title}\n\n${rule.description}\n\n## Solution\n\n${rule.body}\n`
+            : `# ${rule.title}\n\n${rule.description}\n\n${rule.body}\n`;
+        writeFileSync(cachedPath, content, 'utf-8');
+    }
+    return cachedPath;
+};
+/**
+ * Checks if the cached file is outdated compared to the rule's updated_at timestamp
+ */
+const isCacheOutdated = (cachedPath, rule) => {
+    try {
+        const stats = statSync(cachedPath);
+        const cacheTime = stats.mtime.getTime();
+        const ruleTime = new Date(rule.updated_at).getTime();
+        return ruleTime > cacheTime;
+    }
+    catch {
+        return true; // If we can't read the file, consider it outdated
+    }
+};

package/dist/lib/rule-file-ops.d.ts

@@ -3,9 +3,12 @@ export interface PullRuleOptions {
     global?: boolean;
     /** Custom output path (overrides project config and global) */
     outputPath?: string;
+    /** Use symbolic links instead of copying files (default: true) */
+    useSymlink?: boolean;
 }
 /**
- * Pulls a rule or solution to a file. Returns the file path where it was written.
+ * Pulls a rule or solution to a file using symbolic links (like Bun init).
+ * Returns the file path where it was written/linked.
  * Throws if rule not found or if authentication is required.
  */
 export declare const pullRuleToFile: (id: string, options?: PullRuleOptions) => Promise<string>;

package/dist/lib/rule-file-ops.js

@@ -1,14 +1,19 @@
-import { mkdirSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync, lstatSync } from 'fs';
+import { join, relative, dirname } from 'path';
 import { homedir } from 'os';
 import { getRuleById } from '../api/client.js';
 import { getProjectConfig } from '../auth/project-config.js';
 import { ruleFilename, solutionFilename } from './slug.js';
+import { ensureRuleCached } from './rule-cache.js';
 /**
- * Pulls a rule or solution to a file. Returns the file path where it was written.
+ * Pulls a rule or solution to a file using symbolic links (like Bun init).
+ * Returns the file path where it was written/linked.
  * Throws if rule not found or if authentication is required.
  */
 export const pullRuleToFile = async (id, options = {}) => {
+    const useSymlink = options.useSymlink !== false; // Default to true
+    // Ensure rule is cached in central location
+    const cachedPath = await ensureRuleCached(id);
     const rule = await getRuleById(id);
     if (!rule) {
         throw new Error(`Rule or solution with ID ${id} not found.`);
@@ -31,9 +36,41 @@ export const pullRuleToFile = async (id, options = {}) => {
     const filename = rule.kind === 'solution'
         ? join(outDir, solutionFilename(rule.title, rule.id))
         : join(outDir, ruleFilename(rule.title, rule.id));
-    const content = rule.kind === 'solution'
-        ? `# ${rule.title}\n\n${rule.description}\n\n## Solution\n\n${rule.body}\n`
-        : `# ${rule.title}\n\n${rule.description}\n\n${rule.body}\n`;
-    writeFileSync(filename, content);
+    // Remove existing file/symlink if it exists
+    if (existsSync(filename)) {
+        try {
+            const stats = lstatSync(filename);
+            if (stats.isSymbolicLink() || stats.isFile()) {
+                unlinkSync(filename);
+            }
+        }
+        catch {
+            // Ignore errors when removing
+        }
+    }
+    if (useSymlink) {
+        // Create symbolic link to cached file
+        // Use relative path for portability
+        const relativePath = relative(dirname(filename), cachedPath);
+        try {
+            symlinkSync(relativePath, filename);
+        }
+        catch (error) {
+            // Fallback to absolute path if relative fails (e.g., on Windows or cross-filesystem)
+            if (error.code === 'ENOENT' || error.code === 'EXDEV') {
+                symlinkSync(cachedPath, filename);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    else {
+        // Fallback: copy file content (for compatibility or when symlinks aren't desired)
+        const content = rule.kind === 'solution'
+            ? `# ${rule.title}\n\n${rule.description}\n\n## Solution\n\n${rule.body}\n`
+            : `# ${rule.title}\n\n${rule.description}\n\n${rule.body}\n`;
+        writeFileSync(filename, content);
+    }
     return filename;
 };

package/dist/types.d.ts

@@ -10,6 +10,7 @@ export interface Rule {
     technologies?: string[];
     user_id: string;
     author_display_name?: string | null;
+    version?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -21,6 +22,7 @@ export interface RuleInsert {
     context?: string | null;
     examples?: string[];
     technologies?: string[];
+    version?: string;
 }
 export interface StoredCredentials {
     access_token: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitcompass",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "BitCompass CLI - rules, solutions, and MCP server",
   "type": "module",
   "bin": {