Feat/ais use local path symlink (#33)

* docs: fix ais init in Quick Start and enhance init command documentation

- Add ais init to Scenario 2 Option A (create new repo flow) in both READMEs
- Fix incomplete flow: mkdir/cd/git init/ais init/ais use
- Enhance Repository Lifecycle section with init options (--force, --no-dirs, --json)
- Clarify that ais init creates ai-rules-sync.json and source directories

Co-authored-by: lbb <mr@lbb00.com>

* feat: support ais use with local path and symlink for git repos

- ais use ~/path: symlink git repos to repos/, use remote URL for portable config
- Check repos/ conflict and error with clear message
- -t option supports local path with same symlink logic
- Strip credentials from URLs for safe config sharing
- Non-git or no-remote repos: use path directly (legacy behavior)

Co-authored-by: lbb <mr@lbb00.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: lbb00

README.md

@@ -159,11 +159,14 @@ ais cursor add testing
 ```bash
 # 1. Create a rules repository (or use existing one)
 # Option A: Create new repository
-git init ~/my-rules-repo
-ais use ~/my-rules-repo
+mkdir ~/my-rules-repo && cd ~/my-rules-repo
+git init
+ais init
+ais use .
 
-# Option B: Use existing repository
+# Option B: Use existing repository (URL or local path)
 ais use https://github.com/your-org/rules-repo.git
+ais use ~/my-rules-repo
 
 # 2. Import your existing rule
 cd your-project
@@ -211,7 +214,7 @@ my-rules-repo/
 
 **Repository Locations:**
 - **Global**: `~/.config/ai-rules-sync/repos/` (managed by AIS)
-- **Local**: Any local path (for development)
+- **Local**: `ais use ~/path` with a git repo creates a symlink in `repos/`; rules reference the remote URL for portable config
 
 **Managing Repositories:**
 ```bash
@@ -311,7 +314,12 @@ ais update --dry-run
 
 **Option 1: Use an existing repository**
 ```bash
+# Remote URL (cloned to ~/.config/ai-rules-sync/repos/)
 ais use https://github.com/your-org/rules-repo.git
+
+# Local path (git repo with remote: symlinked to repos/; rules reference remote URL)
+ais use ~/my-rules-repo
+ais use ./path/to/repo
 ```
 
 **Option 2: Create a new local repository**
@@ -321,7 +329,7 @@ mkdir ~/my-rules-repo
 cd ~/my-rules-repo
 git init
 
-# Scaffold default ai-rules-sync.json + source directories
+# Scaffold ai-rules-sync.json and create default source directories (.cursor/rules/, etc.)
 ais init
 
 # Set as current repository
@@ -445,11 +453,14 @@ ais update --dry-run
 # Pull updates and reinstall entries from config
 ais update
 
-# Initialize a rules repository template in current directory
+# Initialize a rules repository template (creates ai-rules-sync.json + source dirs)
 ais init
 
-# Initialize template in a subdirectory
+# Initialize in a subdirectory
 ais init my-rules-repo
+
+# Options: --force (overwrite existing), --no-dirs (config only), --json (machine output)
+ais init --help
 ```
 
 ---
@@ -760,7 +771,7 @@ ais use personal-rules
 
 All commands support:
 
-- `-t, --target <repo>`: Specify repository (name or URL)
+- `-t, --target <repo>`: Specify repository (name, URL, or local path)
 - `-l, --local`: Save to `ai-rules-sync.local.json` (private)
 
 Examples:

README_ZH.md

@@ -159,11 +159,14 @@ ais cursor add testing
 ```bash
 # 1. 创建规则仓库（或使用现有仓库）
 # 选项 A：创建新仓库
-git init ~/my-rules-repo
-ais use ~/my-rules-repo
+mkdir ~/my-rules-repo && cd ~/my-rules-repo
+git init
+ais init
+ais use .
 
-# 选项 B：使用现有仓库
+# 选项 B：使用现有仓库（URL 或本地路径）
 ais use https://github.com/your-org/rules-repo.git
+ais use ~/my-rules-repo
 
 # 2. 导入你的现有规则
 cd your-project
@@ -311,7 +314,12 @@ ais update --dry-run
 
 **选项 1：使用现有仓库**
 ```bash
+# 远程 URL（会克隆到 ~/.config/ai-rules-sync/repos/）
 ais use https://github.com/your-org/rules-repo.git
+
+# 本地路径（有 remote 的 git 仓库：会 symlink 到 repos/；规则引用 remote URL）
+ais use ~/my-rules-repo
+ais use ./path/to/repo
 ```
 
 **选项 2：创建新的本地仓库**
@@ -321,7 +329,7 @@ mkdir ~/my-rules-repo
 cd ~/my-rules-repo
 git init
 
-# 生成默认 ai-rules-sync.json 和源目录结构
+# 生成 ai-rules-sync.json 并创建默认源目录（.cursor/rules/ 等）
 ais init
 
 # 设置为当前仓库
@@ -445,11 +453,14 @@ ais update --dry-run
 # 拉取仓库更新并根据配置重装链接
 ais update
 
-# 在当前目录初始化规则仓库模板
+# 初始化规则仓库模板（创建 ai-rules-sync.json 和源目录）
 ais init
 
-# 在子目录初始化模板
+# 在子目录初始化
 ais init my-rules-repo
+
+# 选项：--force（覆盖已有）、--no-dirs（仅配置）、--json（机器输出）
+ais init --help
 ```
 
 ---
@@ -760,7 +771,7 @@ ais use personal-rules
 
 所有命令都支持：
 
-- `-t, --target <repo>`：指定仓库（名称或 URL）
+- `-t, --target <repo>`：指定仓库（名称、URL 或本地路径）
 - `-l, --local`：保存到 `ai-rules-sync.local.json`（私有）
 
 示例：

src/__tests__/use-local-path.test.ts

@@ -0,0 +1,87 @@
+import os from 'os';
+import path from 'path';
+import fs from 'fs-extra';
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import { getConfig, setConfig } from '../config.js';
+import { isLocalPath, resolveLocalPath } from '../utils.js';
+import { isLocalRepo, stripUrlCredentials } from '../git.js';
+
+describe('isLocalPath', () => {
+  it('should return false for URLs', () => {
+    expect(isLocalPath('https://github.com/org/repo.git')).toBe(false);
+    expect(isLocalPath('git@github.com:org/repo.git')).toBe(false);
+    expect(isLocalPath('ssh://git@host/repo')).toBe(false);
+  });
+
+  it('should return false for bare .git suffix (likely URL)', () => {
+    expect(isLocalPath('repo.git')).toBe(false);
+  });
+
+  it('should return true for absolute paths', () => {
+    expect(isLocalPath('/home/user/repo')).toBe(true);
+    expect(isLocalPath('/tmp/repo')).toBe(true);
+  });
+
+  it('should return true for home-relative paths', () => {
+    expect(isLocalPath('~/repo')).toBe(true);
+    expect(isLocalPath('~/my-rules-repo')).toBe(true);
+  });
+
+  it('should return true for relative paths', () => {
+    expect(isLocalPath('./repo')).toBe(true);
+    expect(isLocalPath('../repo')).toBe(true);
+  });
+});
+
+describe('resolveLocalPath', () => {
+  it('should resolve and verify existing directory', async () => {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), 'ais-resolve-'));
+    const subDir = path.join(cwd, 'subdir');
+    await fs.ensureDir(subDir);
+
+    const resolved = await resolveLocalPath('./subdir', cwd);
+    expect(resolved).toBe(subDir);
+
+    const absResolved = await resolveLocalPath(cwd);
+    expect(absResolved).toBe(cwd);
+  });
+
+  it('should return null for non-existent path', async () => {
+    const resolved = await resolveLocalPath('/nonexistent/path/12345');
+    expect(resolved).toBeNull();
+  });
+
+  it('should expand ~ to homedir', async () => {
+    const inHome = path.join(os.homedir(), 'ais-test-dir');
+    await fs.ensureDir(inHome);
+    try {
+      const resolved = await resolveLocalPath('~/ais-test-dir');
+      expect(resolved).toBe(inHome);
+    } finally {
+      await fs.remove(inHome).catch(() => {});
+    }
+  });
+});
+
+describe('isLocalRepo', () => {
+  it('should return true when url is a path', () => {
+    expect(isLocalRepo({ name: 'x', url: '/home/user/repo', path: '/home/user/repo' })).toBe(true);
+    expect(isLocalRepo({ name: 'x', url: '~/repo', path: '/home/user/repo' })).toBe(true);
+  });
+
+  it('should return false when url is a remote URL', () => {
+    expect(isLocalRepo({ name: 'x', url: 'https://github.com/org/repo', path: '/tmp/repo' })).toBe(false);
+    expect(isLocalRepo({ name: 'x', url: 'git@github.com:org/repo.git', path: '/tmp/repo' })).toBe(false);
+  });
+});
+
+describe('stripUrlCredentials', () => {
+  it('should strip credentials from https URL', () => {
+    expect(stripUrlCredentials('https://token@github.com/org/repo.git')).toBe('https://github.com/org/repo.git');
+    expect(stripUrlCredentials('https://user:pass@host/path')).toBe('https://host/path');
+  });
+
+  it('should leave git@ URLs unchanged', () => {
+    expect(stripUrlCredentials('git@github.com:org/repo.git')).toBe('git@github.com:org/repo.git');
+  });
+});

src/commands/helpers.ts

@@ -4,10 +4,12 @@
 
 import path from 'path';
 import chalk from 'chalk';
+import fs from 'fs-extra';
 import { getConfig, setConfig, getReposBaseDir, getCurrentRepo, RepoConfig } from '../config.js';
-import { cloneOrUpdateRepo } from '../git.js';
+import { cloneOrUpdateRepo, getRemoteUrl } from '../git.js';
 import { getCombinedProjectConfig } from '../project-config.js';
 import { stripCopilotSuffix, adapterRegistry } from '../adapters/index.js';
+import { isLocalPath, resolveLocalPath } from '../utils.js';
 
 /**
  * Get the target repository based on CLI options
@@ -60,6 +62,76 @@ export async function getTargetRepo(options: { target?: string }): Promise<RepoC
       return newRepo;
     }
 
+    // 3. Try as local path
+    if (isLocalPath(target)) {
+      const resolvedPath = await resolveLocalPath(target, process.cwd());
+      if (!resolvedPath) {
+        throw new Error(`Path "${target}" does not exist or is not a directory.`);
+      }
+      const remoteUrl = await getRemoteUrl(resolvedPath);
+      const isGit = await fs.pathExists(path.join(resolvedPath, '.git'));
+
+      if (isGit && remoteUrl) {
+        // Git repo with remote: symlink to repos/ and use remote URL
+        let name = path.basename(resolvedPath) || 'local-repo';
+        const symlinkPath = path.join(getReposBaseDir(), name);
+
+        if (config.repos) {
+          for (const repo of Object.values(config.repos)) {
+            if (repo.url === remoteUrl) return repo;
+            if (path.resolve(repo.path) === path.resolve(resolvedPath)) return repo;
+            if (path.resolve(await fs.realpath(repo.path).catch(() => '')) === path.resolve(resolvedPath)) return repo;
+          }
+        }
+
+        if (await fs.pathExists(symlinkPath)) {
+          const stat = await fs.lstat(symlinkPath);
+          if (stat.isSymbolicLink()) {
+            const symTarget = await fs.realpath(symlinkPath);
+            if (path.resolve(symTarget) === path.resolve(resolvedPath)) {
+              const repo = config.repos?.[name] ?? { name, url: remoteUrl, path: symlinkPath };
+              await setConfig({ repos: { ...(config.repos || {}), [name]: repo } });
+              return repo;
+            }
+          }
+          throw new Error(
+            `Repository "${name}" already exists at ${symlinkPath}. ` +
+            `Use "ais use ${name}" or remove it first.`
+          );
+        }
+
+        for (const repo of Object.values(config.repos || {})) {
+          if (repo.url === remoteUrl) {
+            throw new Error(`Repository with remote "${remoteUrl}" is already configured. Use "ais use <name>".`);
+          }
+        }
+
+        await fs.ensureDir(getReposBaseDir());
+        await fs.symlink(resolvedPath, symlinkPath);
+        const newRepo: RepoConfig = { name, url: remoteUrl, path: symlinkPath };
+        await setConfig({ repos: { ...(config.repos || {}), [name]: newRepo } });
+        await cloneOrUpdateRepo(newRepo);
+        return newRepo;
+      }
+
+      // Non-git or no remote: use path directly
+      if (config.repos) {
+        for (const repo of Object.values(config.repos)) {
+          if (path.resolve(repo.path) === path.resolve(resolvedPath)) return repo;
+        }
+      }
+      console.log(chalk.blue(`Using local repository at ${resolvedPath}`));
+      let name = path.basename(resolvedPath) || 'local-repo';
+      if (config.repos && config.repos[name] && config.repos[name].path !== resolvedPath) {
+        name = `${name}-${Date.now()}`;
+      }
+      const url = remoteUrl || resolvedPath;
+      const newRepo: RepoConfig = { name, url, path: resolvedPath };
+      await setConfig({ repos: { ...(config.repos || {}), [name]: newRepo } });
+      await cloneOrUpdateRepo(newRepo);
+      return newRepo;
+    }
+
     throw new Error(`Repository "${target}" not found in configuration.`);
   }
 

src/commands/install.ts

@@ -11,6 +11,7 @@ import { RuleEntry } from '../project-config.js';
 import { getConfig, setConfig, getReposBaseDir, getUserProjectConfig, getUserConfigPath, RepoConfig } from '../config.js';
 import { cloneOrUpdateRepo } from '../git.js';
 import { parseConfigEntry } from './helpers.js';
+import { isLocalPath, resolveLocalPath } from '../utils.js';
 import type { RepoResolverFn } from '../dotany/types.js';
 
 /**
@@ -21,7 +22,7 @@ async function findOrCreateRepo(
     repoUrl: string,
     entryName: string
 ): Promise<RepoConfig> {
-    // Check if repo already exists
+    // Check if repo already exists (by url or by path for local repos)
     for (const k in repos) {
         if (repos[k].url === repoUrl) {
             const repo = repos[k];
@@ -30,9 +31,29 @@ async function findOrCreateRepo(
             }
             return repo;
         }
+        if (path.resolve(repos[k].path) === path.resolve(repoUrl)) {
+            return repos[k];
+        }
+    }
+
+    // Local path: use directly if it exists
+    if (isLocalPath(repoUrl)) {
+        const resolvedPath = await resolveLocalPath(repoUrl, process.cwd());
+        if (resolvedPath) {
+            let name = path.basename(resolvedPath) || `repo-${Date.now()}`;
+            if (repos[name]) name = `${name}-${Date.now()}`;
+            const repoConfig: RepoConfig = { name, url: resolvedPath, path: resolvedPath };
+            await setConfig({ repos: { ...repos, [name]: repoConfig } });
+            repos[name] = repoConfig;
+            return repoConfig;
+        }
+        throw new Error(
+            `Local repository path "${repoUrl}" does not exist. ` +
+            `Run "ais use <path>" first if this is a shared project.`
+        );
     }
 
-    // Create new repo config
+    // Create new repo config (remote URL)
     console.log(chalk.yellow(`Repository for ${entryName} not found locally. Configuring...`));
 
     let name = path.basename(repoUrl, '.git');