ads-fe 0.0.1

package/README.md

@@ -0,0 +1,99 @@
+# ads-fe skill CLI
+
+一个基于 TypeScript 和 commander 实现的动态 skill 发现与获取工具。
+
+## 安装
+
+```bash
+pnpm install
+pnpm build
+```
+
+## 全局 npm 用法
+
+当这个包发布到 npm 后，开发者可以全局安装 CLI：
+
+```bash
+npm i -g ads-fe
+ads-fe init codex
+ads-fe init claude
+ads-fe init cursor
+```
+
+使用 `all` 安装所有支持的目标：
+
+```bash
+ads-fe init all
+```
+
+默认情况下，`ads-fe init <agent>` 会安装到用户的全局 agent 配置中，因此该 skill 可以在任意项目中使用。
+
+如需安装到当前项目：
+
+```bash
+ads-fe init codex --project
+ads-fe init claude --project
+ads-fe init cursor --project
+```
+
+`ads-fe init <agent>` 会把这个包内置的 skill 安装到 AI agent 中。
+
+`ads-fe skill init` 与上面的命令不同：它会初始化外部 skill 源仓库，这些仓库用于维护本包。
+
+## 命令
+
+```bash
+ads-fe init codex  # skill 安装到 codex 全局
+ads-fe init claude # skill 安装到 claude code 全局
+ads-fe init cursor                    # skill 安装到 cursor 全局
+ads-fe init all --project             # 项目级安装
+
+# for ai 
+ads-fe skill list # 内置 skill 列表
+ads-fe skill list --json # json 格式输出内置 skill 列表
+ads-fe skill get core  # 获取对应 skill.md
+ads-fe skill get core --json # json 格式输出对应 skill 
+ads-fe skill get core --full # 全量输出对应 skill
+ads-fe skill get core --full --json
+ads-fe skill path core # 获取对应 skill 路径
+
+# for 内置 skill 更新维护
+ads-fe skill init
+ads-fe skill sync
+ads-fe skill sync --no-update
+ads-fe skill update
+ads-fe skill check
+ads-fe skill cleanup --dry-run
+```
+
+## 动态发现行为
+
+发现顺序：
+
+1. 如果设置了 `ADSPOWER_SKILLS_DIR`，则按操作系统的路径分隔符拆分，并优先扫描这些目录。
+2. 否则扫描项目根目录下的 `skills/` 和 `skills/`。
+
+对于每个子目录，如果存在 `SKILL.md`，就会在运行时被发现。
+Frontmatter 字段：
+
+- `name`
+- `description`
+- `hidden`
+
+`get` 每次调用都会重新执行发现流程，并动态读取当前文件内容。
+
+`get --full` 会递归返回目标 skill 目录中的所有文件
+（例如 `references/`、`templates/`、`scripts/`）。
+
+## 外部官方 skills
+
+外部仓库定义在 `src/meta.ts` 中。
+
+- `skill init` 会添加缺失的 `sources/<name>` 和 `vendor/<name>` git submodule。
+- `skill sync` 会更新 submodule，然后把配置的 `vendor/<name>/skills/<source>` 目录复制到 `skills/<output>`。
+- `skill sync --no-update` 会从当前本地 vendor checkout 复制，不执行拉取。
+- `skill update` 是显式的更新并同步命令。
+- `skill check` 会 fetch 已初始化的 submodule，并报告每个 submodule 落后 upstream 多少个 commit。
+- `skill cleanup` 会删除不再列在 `src/meta.ts` 中的陈旧生成项；来自 `manual` 的手动 skills 会被保留。
+
+每个同步得到的 skill 都会获得一个 `SYNC.md` 文件，其中包含来源路径、git SHA 和同步日期。如果 vendor 仓库根目录存在 license 文件，它会被复制为 `LICENSE.md`。

package/dist/cli.js

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { manual, submodules, vendors } from './meta.js';
+const SKILL_DIRS = ['skills', 'skills'];
+const SKILL_FILE = 'SKILL.md';
+const ENV_SKILLS_DIR = 'ADSPOWER_SKILLS_DIR';
+const GENERATED_SKILL_DIR = 'skills';
+function readFrontmatter(content) {
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!fmMatch)
+        return {};
+    const block = fmMatch[1];
+    const meta = {};
+    for (const line of block.split('\n')) {
+        const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+        if (!m)
+            continue;
+        const key = m[1].trim();
+        let value = m[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key === 'name')
+            meta.name = value;
+        if (key === 'description')
+            meta.description = value;
+        if (key === 'hidden')
+            meta.hidden = /^true$/i.test(value);
+    }
+    return meta;
+}
+function detectCliPackageRoot() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (fs.existsSync(path.join(dir, 'package.json')) && fs.existsSync(path.join(dir, 'skill.md'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return process.cwd();
+        dir = parent;
+    }
+}
+function detectPackageRoot() {
+    return process.cwd();
+}
+function detectSkillPackageRoot() {
+    const cliRoot = detectCliPackageRoot();
+    if (fs.existsSync(path.join(cliRoot, 'skill.md')))
+        return cliRoot;
+    return detectPackageRoot();
+}
+function runGit(args, cwd = detectPackageRoot()) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    }).trim();
+}
+function runGitSafe(args, cwd = detectPackageRoot()) {
+    try {
+        return runGit(args, cwd);
+    }
+    catch {
+        return null;
+    }
+}
+function allExternalProjects() {
+    return [
+        ...Object.entries(submodules).map(([name, url]) => ({
+            name,
+            url,
+            type: 'source',
+            dir: path.join('sources', name),
+        })),
+        ...Object.entries(vendors).map(([name, config]) => ({
+            name,
+            url: config.source,
+            type: 'vendor',
+            dir: path.join('vendor', name),
+        })),
+    ];
+}
+function readGitmodulePaths() {
+    const gitmodules = path.join(detectPackageRoot(), '.gitmodules');
+    if (!fs.existsSync(gitmodules))
+        return new Set();
+    const content = fs.readFileSync(gitmodules, 'utf8');
+    const paths = [...content.matchAll(/path\s*=\s*(.+)/g)].map((m) => m[1].trim());
+    return new Set(paths);
+}
+function copyDirectory(sourceDir, outputDir) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const outputPath = path.join(outputDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirectory(sourcePath, outputPath);
+            continue;
+        }
+        if (entry.isFile()) {
+            fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+            fs.copyFileSync(sourcePath, outputPath);
+        }
+    }
+}
+function removePath(target) {
+    fs.rmSync(target, { recursive: true, force: true });
+}
+function copyDirectoryIfExists(sourceDir, outputDir) {
+    if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory())
+        return false;
+    removePath(outputDir);
+    copyDirectory(sourceDir, outputDir);
+    return true;
+}
+function writeFileEnsured(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+}
+function userHome() {
+    return os.homedir();
+}
+function cursorUserRulesDir() {
+    if (process.platform === 'darwin')
+        return path.join(userHome(), 'Library', 'Application Support', 'Cursor', 'User', 'rules');
+    if (process.platform === 'win32') {
+        const base = process.env.APPDATA || path.join(userHome(), 'AppData', 'Roaming');
+        return path.join(base, 'Cursor', 'User', 'rules');
+    }
+    const base = process.env.XDG_CONFIG_HOME || path.join(userHome(), '.config');
+    return path.join(base, 'Cursor', 'User', 'rules');
+}
+function agentSkillDir(agent, scope) {
+    if (scope === 'project') {
+        if (agent === 'claude')
+            return path.join(process.cwd(), '.claude', 'skills', 'ads-fe');
+        if (agent === 'codex')
+            return path.join(process.cwd(), '.codex', 'skills', 'ads-fe');
+        return path.join(process.cwd(), '.cursor', 'rules');
+    }
+    if (agent === 'claude')
+        return path.join(userHome(), '.claude', 'skills', 'ads-fe');
+    if (agent === 'codex')
+        return path.join(userHome(), '.codex', 'skills', 'ads-fe');
+    return cursorUserRulesDir();
+}
+function readRootSkill(root) {
+    const skillPath = path.join(root, 'skill.md');
+    if (!fs.existsSync(skillPath))
+        throw new Error(`Missing package skill file: ${skillPath}`);
+    return fs.readFileSync(skillPath, 'utf8');
+}
+function installSkillDirectory(agent, scope, root) {
+    const targetDir = agentSkillDir(agent, scope);
+    const warnings = [];
+    removePath(targetDir);
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.copyFileSync(path.join(root, 'skill.md'), path.join(targetDir, SKILL_FILE));
+    if (!copyDirectoryIfExists(path.join(root, 'skills'), path.join(targetDir, 'skills'))) {
+        warnings.push(`Missing skills directory: ${path.join(root, 'skills')}`);
+    }
+    return { agent, scope, paths: [targetDir], warnings };
+}
+function cursorRuleContent(rootSkill, dataPath, isProject) {
+    const relOrAbsDataPath = isProject ? '.cursor/rules/ads-fe-skills' : dataPath;
+    return `---
+description: AdsPower frontend skill
+globs:
+alwaysApply: true
+---
+
+# AdsPower Frontend Skill
+
+Supporting skill data is installed at \`${relOrAbsDataPath}\`.
+
+${rootSkill.trim()}
+`;
+}
+function installCursor(scope, root) {
+    const targetBase = agentSkillDir('cursor', scope);
+    const rulePath = path.join(targetBase, scope === 'project' ? 'ads-fe.mdc' : 'ads-fe.md');
+    const dataPath = path.join(targetBase, 'ads-fe-skills');
+    const warnings = [];
+    const rootSkill = readRootSkill(root);
+    if (!copyDirectoryIfExists(path.join(root, 'skills'), dataPath)) {
+        warnings.push(`Missing skills directory: ${path.join(root, 'skills')}`);
+    }
+    writeFileEnsured(rulePath, cursorRuleContent(rootSkill, dataPath, scope === 'project'));
+    return { agent: 'cursor', scope, paths: [rulePath, dataPath], warnings };
+}
+function installAgent(agent, scope, root) {
+    if (agent === 'cursor')
+        return installCursor(scope, root);
+    readRootSkill(root);
+    return installSkillDirectory(agent, scope, root);
+}
+function getGitSha(dir) {
+    return runGitSafe(['rev-parse', 'HEAD'], dir);
+}
+function copyLicense(vendorPath, outputPath) {
+    const names = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'license', 'license.md', 'license.txt'];
+    const licensePath = names.map((name) => path.join(vendorPath, name)).find((candidate) => fs.existsSync(candidate));
+    if (licensePath)
+        fs.copyFileSync(licensePath, path.join(outputPath, 'LICENSE.md'));
+}
+function syncVendorSkills() {
+    const root = detectPackageRoot();
+    const synced = [];
+    const skipped = [];
+    for (const [vendorName, config] of Object.entries(vendors)) {
+        const vendorPath = path.join(root, 'vendor', vendorName);
+        const vendorSkillsPath = path.join(vendorPath, 'skills');
+        if (!fs.existsSync(vendorSkillsPath)) {
+            skipped.push(`vendor/${vendorName}/skills`);
+            continue;
+        }
+        for (const [sourceSkillName, outputSkillName] of Object.entries(config.skills)) {
+            const sourceSkillPath = path.join(vendorSkillsPath, sourceSkillName);
+            const outputPath = path.join(root, GENERATED_SKILL_DIR, outputSkillName);
+            if (!fs.existsSync(sourceSkillPath)) {
+                skipped.push(`vendor/${vendorName}/skills/${sourceSkillName}`);
+                continue;
+            }
+            fs.rmSync(outputPath, { recursive: true, force: true });
+            copyDirectory(sourceSkillPath, outputPath);
+            copyLicense(vendorPath, outputPath);
+            const sha = getGitSha(vendorPath) || 'unknown';
+            const date = new Date().toISOString().slice(0, 10);
+            fs.writeFileSync(path.join(outputPath, 'SYNC.md'), `# Sync Info
+
+- Source: \`vendor/${vendorName}/skills/${sourceSkillName}\`
+- Git SHA: \`${sha}\`
+- Synced: ${date}
+`);
+            synced.push(`${sourceSkillName} -> ${outputSkillName}`);
+        }
+    }
+    return { synced, skipped };
+}
+function expectedGeneratedSkillNames() {
+    const expected = new Set();
+    for (const config of Object.values(vendors)) {
+        for (const outputName of Object.values(config.skills))
+            expected.add(outputName);
+    }
+    return expected;
+}
+function findSkillDirs() {
+    const fromEnv = process.env[ENV_SKILLS_DIR];
+    if (fromEnv) {
+        const dirs = fromEnv
+            .split(path.delimiter)
+            .map((p) => p.trim())
+            .filter(Boolean)
+            .map((p) => path.resolve(p))
+            .filter((p) => fs.existsSync(p) && fs.statSync(p).isDirectory());
+        if (dirs.length > 0)
+            return dirs;
+    }
+    const root = detectPackageRoot();
+    return SKILL_DIRS
+        .map((d) => path.join(root, d))
+        .filter((p) => fs.existsSync(p) && fs.statSync(p).isDirectory());
+}
+function discoverSkills(includeHidden = false) {
+    const dirs = findSkillDirs();
+    const skills = new Map();
+    for (const baseDir of dirs) {
+        const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const skillDir = path.join(baseDir, entry.name);
+            const skillFile = path.join(skillDir, SKILL_FILE);
+            if (!fs.existsSync(skillFile))
+                continue;
+            const content = fs.readFileSync(skillFile, 'utf8');
+            const meta = readFrontmatter(content);
+            const name = meta.name?.trim() || entry.name;
+            const hidden = Boolean(meta.hidden);
+            if (hidden && !includeHidden)
+                continue;
+            if (!skills.has(name)) {
+                skills.set(name, {
+                    meta: {
+                        name,
+                        description: meta.description || '',
+                        hidden,
+                    },
+                    dir: skillDir,
+                    file: skillFile,
+                });
+            }
+        }
+    }
+    return Array.from(skills.values()).sort((a, b) => a.meta.name.localeCompare(b.meta.name));
+}
+function getSkillByName(name, includeHidden = true) {
+    return discoverSkills(includeHidden).find((s) => s.meta.name === name);
+}
+function collectFilesRecursive(dir) {
+    const out = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...collectFilesRecursive(fullPath));
+            continue;
+        }
+        if (entry.isFile())
+            out.push(fullPath);
+    }
+    return out.sort((a, b) => a.localeCompare(b));
+}
+const program = new Command();
+program.name('ads-fe');
+program
+    .command('init <agent>')
+    .description('Install the bundled AdsPower skill into claude, codex, cursor, or all')
+    .option('--project', 'Install into the current project instead of the global user location')
+    .action((agent, opts) => {
+    const allowed = new Set(['claude', 'codex', 'cursor', 'all']);
+    if (!allowed.has(agent)) {
+        process.stderr.write(`Unknown agent: ${agent}. Expected one of: claude, codex, cursor, all\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const scope = opts.project ? 'project' : 'global';
+    const root = detectSkillPackageRoot();
+    const agents = agent === 'all' ? ['claude', 'codex', 'cursor'] : [agent];
+    try {
+        for (const targetAgent of agents) {
+            const result = installAgent(targetAgent, scope, root);
+            for (const targetPath of result.paths)
+                process.stdout.write(`Installed ${result.agent} ${result.scope}: ${targetPath}\n`);
+            for (const warning of result.warnings)
+                process.stderr.write(`Warning: ${warning}\n`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    }
+});
+const skill = program.command('skill').description('Manage skills');
+skill
+    .command('init')
+    .description('Add missing external skill repositories as git submodules')
+    .action(() => {
+    const root = detectPackageRoot();
+    const existing = readGitmodulePaths();
+    const projects = allExternalProjects().filter((project) => !existing.has(project.dir));
+    if (projects.length === 0) {
+        process.stdout.write('All external skill repositories are already initialized.\n');
+        return;
+    }
+    for (const project of projects) {
+        fs.mkdirSync(path.join(root, path.dirname(project.dir)), { recursive: true });
+        runGit(['submodule', 'add', project.url, project.dir], root);
+        process.stdout.write(`Added ${project.type} submodule: ${project.dir}\n`);
+    }
+});
+skill
+    .command('sync')
+    .description('Sync configured vendor skills into skills')
+    .option('--no-update', 'Skip git submodule update before copying skills')
+    .option('--json', 'Output JSON')
+    .action((opts) => {
+    const root = detectPackageRoot();
+    if (opts.update !== false) {
+        runGit(['submodule', 'update', '--remote', '--merge'], root);
+    }
+    const result = syncVendorSkills();
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    for (const item of result.synced)
+        process.stdout.write(`Synced ${item}\n`);
+    for (const item of result.skipped)
+        process.stderr.write(`Skipped missing ${item}\n`);
+});
+skill
+    .command('update')
+    .description('Update external repositories and sync vendor skills into skills')
+    .option('--json', 'Output JSON')
+    .action((opts) => {
+    runGit(['submodule', 'update', '--remote', '--merge'], detectPackageRoot());
+    const result = syncVendorSkills();
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    for (const item of result.synced)
+        process.stdout.write(`Synced ${item}\n`);
+    for (const item of result.skipped)
+        process.stderr.write(`Skipped missing ${item}\n`);
+});
+skill
+    .command('check')
+    .description('Check whether external skill repositories have upstream updates')
+    .option('--json', 'Output JSON')
+    .action((opts) => {
+    const root = detectPackageRoot();
+    runGitSafe(['submodule', 'foreach', 'git fetch'], root);
+    const rows = allExternalProjects()
+        .map((project) => {
+        const projectPath = path.join(root, project.dir);
+        const behind = fs.existsSync(projectPath)
+            ? Number.parseInt(runGitSafe(['rev-list', 'HEAD..@{u}', '--count'], projectPath) || '0', 10)
+            : null;
+        return { name: project.name, type: project.type, path: project.dir, behind };
+    })
+        .filter((row) => row.behind !== null);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+        return;
+    }
+    if (rows.length === 0) {
+        process.stdout.write('No initialized external skill repositories found.\n');
+        return;
+    }
+    for (const row of rows) {
+        process.stdout.write(`${row.path}\t${row.behind} commits behind\n`);
+    }
+});
+skill
+    .command('cleanup')
+    .description('Remove generated skills entries that are no longer listed in src/meta.ts')
+    .option('--dry-run', 'Print stale generated skills without removing them')
+    .action((opts) => {
+    const root = detectPackageRoot();
+    const generatedDir = path.join(root, GENERATED_SKILL_DIR);
+    if (!fs.existsSync(generatedDir))
+        return;
+    const expected = expectedGeneratedSkillNames();
+    for (const entry of fs.readdirSync(generatedDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || manual.includes(entry.name) || expected.has(entry.name))
+            continue;
+        const target = path.join(generatedDir, entry.name);
+        if (opts.dryRun) {
+            process.stdout.write(`Stale generated skill: ${entry.name}\n`);
+        }
+        else {
+            fs.rmSync(target, { recursive: true, force: true });
+            process.stdout.write(`Removed stale generated skill: ${entry.name}\n`);
+        }
+    }
+});
+skill
+    .command('list')
+    .option('--json', 'Output JSON')
+    .option('--all', 'Include hidden skills')
+    .action((opts) => {
+    const rows = discoverSkills(Boolean(opts.all)).map((s) => ({
+        name: s.meta.name,
+        description: s.meta.description || '',
+        hidden: Boolean(s.meta.hidden),
+        path: s.file,
+    }));
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+        return;
+    }
+    for (const row of rows) {
+        process.stdout.write(`${row.name}\t${row.description}\n`);
+    }
+});
+skill
+    .command('path <name>')
+    .option('--json', 'Output JSON')
+    .action((name, opts) => {
+    const target = getSkillByName(name, true);
+    if (!target) {
+        process.stderr.write(`Skill not found: ${name}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ name, path: target.file }, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`${target.file}\n`);
+});
+skill
+    .command('get <name>')
+    .option('--full', 'Return all files under the skill directory')
+    .option('--json', 'Output JSON')
+    .action((name, opts) => {
+    const target = getSkillByName(name, true);
+    if (!target) {
+        process.stderr.write(`Skill not found: ${name}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const isFull = Boolean(opts.full);
+    if (isFull) {
+        const files = collectFilesRecursive(target.dir).map((filePath) => {
+            const relPath = path.relative(target.dir, filePath).split(path.sep).join('/');
+            const content = fs.readFileSync(filePath, 'utf8');
+            return { path: relPath, content };
+        });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({
+                name: target.meta.name,
+                description: target.meta.description || '',
+                hidden: Boolean(target.meta.hidden),
+                path: target.file,
+                dir: target.dir,
+                files,
+            }, null, 2)}\n`);
+            return;
+        }
+        for (const file of files) {
+            process.stdout.write(`--- FILE: ${file.path} ---\n`);
+            process.stdout.write(file.content);
+            if (!file.content.endsWith('\n'))
+                process.stdout.write('\n');
+            process.stdout.write('\n');
+        }
+        return;
+    }
+    const content = fs.readFileSync(target.file, 'utf8');
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            name: target.meta.name,
+            description: target.meta.description || '',
+            hidden: Boolean(target.meta.hidden),
+            path: target.file,
+            content,
+        }, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(content);
+    if (!content.endsWith('\n'))
+        process.stdout.write('\n');
+});
+program.parse();