@mison/ling 1.0.0

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mison/ling",
+  "version": "1.0.0",
+  "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MisonL/Ling.git"
+  },
+  "homepage": "https://github.com/MisonL/Ling#readme",
+  "bugs": {
+    "url": "https://github.com/MisonL/Ling/issues"
+  },
+  "keywords": [
+    "ling",
+    "ai",
+    "agent",
+    "gemini",
+    "skills",
+    "templates"
+  ],
+  "author": "vudovn",
+  "license": "MIT",
+  "scripts": {
+    "clean": "node scripts/clean.js",
+    "clean:dry-run": "node scripts/clean.js --dry-run",
+    "health-check": "node scripts/health-check.js",
+    "postinstall": "node scripts/postinstall-check.js",
+    "test": "node scripts/run-tests.js",
+    "ci:verify": "node scripts/ci-verify.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".agents/**",
+    ".spec/**",
+    "bin/**",
+    "scripts/clean.js",
+    "scripts/ci-verify.js",
+    "scripts/health-check.js",
+    "scripts/health-check.sh",
+    "scripts/postinstall-check.js",
+    "scripts/run-tests.js",
+    "tests/**/*.test.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "AGENT_FLOW.md",
+    "docs/PLAN.md",
+    "docs/TECH.md"
+  ],
+  "bin": {
+    "ling": "./bin/ling.js",
+    "ag-kit": "./bin/ag-kit.js"
+  }
+}

package/scripts/ci-verify.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const REPO_ROOT = path.resolve(__dirname, "..");
+const CLI_PATH = path.join(REPO_ROOT, "bin", "ling.js");
+
+function runCli(args, options = {}) {
+    const env = {
+        ...process.env,
+        LING_SKIP_UPSTREAM_CHECK: "1",
+        ...options.env,
+    };
+
+    const result = spawnSync(process.execPath, [CLI_PATH, ...args], {
+        cwd: REPO_ROOT,
+        env,
+        encoding: "utf8",
+    });
+
+    if (result.status !== 0) {
+        const message = result.stderr || result.stdout || "";
+        throw new Error(`命令失败: ling ${args.join(" ")}\n${message}`);
+    }
+
+    return result.stdout || "";
+}
+
+function ensureExists(targetPath, label) {
+    if (!fs.existsSync(targetPath)) {
+        throw new Error(`缺少 ${label}: ${targetPath}`);
+    }
+}
+
+function main() {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-ci-"));
+    const workspaceDir = path.join(tempRoot, "workspace");
+    const indexPath = path.join(tempRoot, "workspaces.json");
+    const globalRoot = path.join(tempRoot, "global-root");
+
+    fs.mkdirSync(workspaceDir, { recursive: true });
+
+    const env = {
+        LING_INDEX_PATH: indexPath,
+        LING_GLOBAL_ROOT: globalRoot,
+    };
+
+    runCli(["init", "--targets", "gemini,codex", "--path", workspaceDir, "--quiet"], { env });
+
+    const status = runCli(["status", "--path", workspaceDir, "--quiet"], { env }).trim();
+    if (status !== "installed") {
+        throw new Error(`status 结果异常: ${status}`);
+    }
+
+    runCli(["doctor", "--path", workspaceDir, "--quiet"], { env });
+    runCli(["update", "--path", workspaceDir, "--quiet"], { env });
+    runCli(["update-all", "--dry-run", "--quiet"], { env });
+
+    runCli(["exclude", "add", "--path", workspaceDir, "--quiet"], { env });
+    const excluded = runCli(["exclude", "list", "--quiet"], { env });
+    if (!excluded.split(/\r?\n/).includes(workspaceDir)) {
+        throw new Error("exclude add 未生效");
+    }
+    runCli(["exclude", "remove", "--path", workspaceDir, "--quiet"], { env });
+    const excludedAfter = runCli(["exclude", "list", "--quiet"], { env });
+    if (excludedAfter.split(/\r?\n/).includes(workspaceDir)) {
+        throw new Error("exclude remove 未生效");
+    }
+
+    runCli(["global", "sync", "--quiet"], { env });
+    const globalStatus = runCli(["global", "status", "--quiet"], { env }).trim();
+    if (globalStatus !== "installed") {
+        throw new Error(`global status 结果异常: ${globalStatus}`);
+    }
+
+    runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+    const specStatus = runCli(["spec", "status", "--quiet"], { env }).trim();
+    if (specStatus !== "installed") {
+        throw new Error(`spec status 结果异常: ${specStatus}`);
+    }
+    runCli(["spec", "disable", "--target", "codex", "--quiet"], { env });
+    const specStatusAfterDisable = runCli(["spec", "status", "--quiet"], { env }).trim();
+    if (specStatusAfterDisable !== "missing") {
+        throw new Error(`spec disable 后状态异常: ${specStatusAfterDisable}`);
+    }
+
+    const codexSkill = path.join(globalRoot, ".codex", "skills", "workflow-plan", "SKILL.md");
+    const geminiCliSkill = path.join(globalRoot, ".gemini", "skills", "clean-code", "SKILL.md");
+    const antigravitySkill = path.join(globalRoot, ".gemini", "antigravity", "skills", "clean-code", "SKILL.md");
+    const specCodexSkill = path.join(globalRoot, ".codex", "skills", "harness-engineering");
+    ensureExists(codexSkill, "全局 Codex workflow-plan Skill");
+    ensureExists(geminiCliSkill, "全局 Gemini CLI clean-code Skill");
+    ensureExists(antigravitySkill, "全局 Antigravity clean-code Skill");
+    if (fs.existsSync(specCodexSkill)) {
+        throw new Error(`spec disable 后仍残留 Spec Skill: ${specCodexSkill}`);
+    }
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+try {
+    main();
+    console.log("[ok] CI 全链路演练通过");
+} catch (err) {
+    console.error(`[error] ${err.message}`);
+    process.exit(1);
+}

package/scripts/clean.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_RELATIVE_TARGETS = [
+    ".temp_ag_kit",
+    "coverage",
+    "web/.next",
+    "web/node_modules",
+    "web/out",
+    "web/.turbo",
+];
+
+function parseArgs(argv) {
+    const options = {
+        dryRun: false,
+        quiet: false,
+    };
+
+    for (const arg of argv) {
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--quiet") {
+            options.quiet = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+            continue;
+        }
+        throw new Error(`未知参数: ${arg}`);
+    }
+
+    return options;
+}
+
+function removeTarget(rootDir, relativePath, options) {
+    const absolutePath = path.join(rootDir, relativePath);
+    const exists = fs.existsSync(absolutePath);
+    const result = {
+        path: relativePath,
+        absolutePath,
+        action: "skipped",
+        reason: "",
+    };
+
+    if (!exists) {
+        result.reason = "not_found";
+        return result;
+    }
+
+    if (options.dryRun) {
+        result.action = "would_remove";
+        return result;
+    }
+
+    fs.rmSync(absolutePath, { recursive: true, force: true });
+    result.action = "removed";
+    return result;
+}
+
+function runClean(options = {}) {
+    const rootDir = path.resolve(options.rootDir || path.join(__dirname, ".."));
+    const targets = Array.isArray(options.targets) && options.targets.length > 0
+        ? options.targets
+        : DEFAULT_RELATIVE_TARGETS;
+
+    const normalizedOptions = {
+        dryRun: Boolean(options.dryRun),
+        quiet: Boolean(options.quiet),
+    };
+
+    const results = targets.map((targetPath) => removeTarget(rootDir, targetPath, normalizedOptions));
+    const removedCount = results.filter((item) => item.action === "removed").length;
+    const wouldRemoveCount = results.filter((item) => item.action === "would_remove").length;
+    const skippedCount = results.filter((item) => item.action === "skipped").length;
+
+    if (!normalizedOptions.quiet) {
+        for (const item of results) {
+            if (item.action === "removed") {
+                console.log(`[clean] 已清理: ${item.path}`);
+                continue;
+            }
+            if (item.action === "would_remove") {
+                console.log(`[dry-run] 将清理: ${item.path}`);
+                continue;
+            }
+            console.log(`[skip] 已跳过: ${item.path} (${item.reason})`);
+        }
+        console.log(`[summary] 清理完成: removed=${removedCount}, dryRun=${wouldRemoveCount}, skipped=${skippedCount}`);
+    }
+
+    return {
+        rootDir,
+        removedCount,
+        wouldRemoveCount,
+        skippedCount,
+        results,
+    };
+}
+
+if (require.main === module) {
+    try {
+        const options = parseArgs(process.argv.slice(2));
+        if (options.help) {
+            console.log("用法: node scripts/clean.js [--dry-run] [--quiet]");
+            process.exit(0);
+        }
+        runClean(options);
+    } catch (err) {
+        console.error(`[error] ${err.message}`);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    DEFAULT_RELATIVE_TARGETS,
+    parseArgs,
+    runClean,
+};

package/scripts/health-check.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const ROOT_DIR = path.resolve(__dirname, "..");
+
+function logStep(message) {
+    console.log(`[health-check] ${message}`);
+}
+
+function runCommand(command, options = {}) {
+    const result = spawnSync(command, {
+        cwd: options.cwd || ROOT_DIR,
+        env: {
+            ...process.env,
+            ...options.env,
+        },
+        encoding: "utf8",
+        shell: true,
+    });
+
+    if (result.status !== 0) {
+        const detail = result.stderr || result.stdout || "";
+        throw new Error(`${command}\n${detail}`.trim());
+    }
+
+    return result.stdout || "";
+}
+
+function commandExists(command) {
+    const probe = spawnSync(command, {
+        encoding: "utf8",
+        shell: true,
+        stdio: "ignore",
+    });
+    return probe.status === 0;
+}
+
+function main() {
+    logStep("检查运行环境");
+    if (!commandExists("node --version")) {
+        throw new Error("缺少命令: node");
+    }
+
+    const packageRunner = commandExists("bun --version") ? "bun" : "npm";
+    if (!commandExists(`${packageRunner} --version`)) {
+        throw new Error(`缺少命令: ${packageRunner}`);
+    }
+
+    logStep("执行测试套件");
+    if (packageRunner === "bun") {
+        runCommand("bun run test");
+    } else {
+        runCommand("npm test --silent");
+    }
+
+    logStep("验证 CLI 核心链路");
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ling-health-check-"));
+    try {
+        const workspaceDir = path.join(tempRoot, "workspace");
+        const indexPath = path.join(tempRoot, "workspaces.json");
+        const globalRoot = path.join(tempRoot, "global-root");
+        fs.mkdirSync(workspaceDir, { recursive: true });
+
+        const env = {
+            LING_INDEX_PATH: indexPath,
+            LING_GLOBAL_ROOT: globalRoot,
+            LING_SKIP_UPSTREAM_CHECK: "1",
+        };
+
+        runCommand(`node bin/ling.js init --targets gemini,codex --path "${workspaceDir}" --quiet`, { env });
+
+        const status = runCommand(`node bin/ling.js status --path "${workspaceDir}" --quiet`, { env }).trim();
+        if (status !== "installed") {
+            throw new Error(`status 结果异常: ${status}`);
+        }
+
+        runCommand(`node bin/ling.js doctor --path "${workspaceDir}" --quiet`, { env });
+        runCommand(`node bin/ling.js update --path "${workspaceDir}" --quiet`, { env });
+        runCommand("node bin/ling.js update-all --dry-run --quiet", { env });
+        runCommand(`node bin/ling.js exclude add --path "${workspaceDir}" --quiet`, { env });
+
+        const excluded = runCommand("node bin/ling.js exclude list --quiet", { env });
+        if (!excluded.split(/\r?\n/).includes(workspaceDir)) {
+            throw new Error("exclude add 未生效");
+        }
+
+        runCommand(`node bin/ling.js exclude remove --path "${workspaceDir}" --quiet`, { env });
+        const excludedAfter = runCommand("node bin/ling.js exclude list --quiet", { env });
+        if (excludedAfter.split(/\r?\n/).includes(workspaceDir)) {
+            throw new Error("exclude remove 未生效");
+        }
+
+        runCommand("node bin/ling.js global sync --quiet", { env });
+        const globalStatus = runCommand("node bin/ling.js global status --quiet", { env }).trim();
+        if (globalStatus !== "installed") {
+            throw new Error(`global status 结果异常: ${globalStatus}`);
+        }
+
+        runCommand("node bin/ling.js spec enable --target codex --quiet", { env });
+        const specStatus = runCommand("node bin/ling.js spec status --quiet", { env }).trim();
+        if (specStatus !== "installed") {
+            throw new Error(`spec status 结果异常: ${specStatus}`);
+        }
+        runCommand("node bin/ling.js spec disable --target codex --quiet", { env });
+        const specStatusAfterDisable = runCommand("node bin/ling.js spec status --quiet", { env }).trim();
+        if (specStatusAfterDisable !== "missing") {
+            throw new Error(`spec disable 后状态异常: ${specStatusAfterDisable}`);
+        }
+
+        const globalChecks = [
+            path.join(globalRoot, ".codex", "skills", "workflow-plan", "SKILL.md"),
+            path.join(globalRoot, ".gemini", "skills", "clean-code", "SKILL.md"),
+            path.join(globalRoot, ".gemini", "antigravity", "skills", "clean-code", "SKILL.md"),
+        ];
+        for (const targetPath of globalChecks) {
+            if (!fs.existsSync(targetPath)) {
+                throw new Error(`global sync 未生成预期文件: ${targetPath}`);
+            }
+        }
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+
+    logStep("执行清理预检");
+    if (packageRunner === "bun") {
+        runCommand("bun run clean:dry-run");
+    } else {
+        runCommand("npm run clean:dry-run --silent");
+    }
+
+    console.log("[ok] 健康检查通过");
+}
+
+try {
+    main();
+} catch (err) {
+    console.error(`[error] ${err.message}`);
+    process.exit(1);
+}

package/scripts/health-check.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+node "${ROOT_DIR}/scripts/health-check.js" "$@"

package/scripts/postinstall-check.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const readline = require("node:readline");
+const { stdin: input, stdout: output } = require("node:process");
+
+const UPSTREAM_GLOBAL_PACKAGE = "@vudovn/ag-kit";
+
+const { readGlobalNpmDependencies } = require("../bin/utils");
+
+function canPromptUser() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+
+function askQuestion(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input, output });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+function parseYesNo(answer, defaultYes) {
+    const text = String(answer || "").trim().toLowerCase();
+    if (!text) {
+        return defaultYes;
+    }
+    if (["y", "yes", "1", "true", "是"].includes(text)) {
+        return true;
+    }
+    if (["n", "no", "0", "false", "否"].includes(text)) {
+        return false;
+    }
+    return defaultYes;
+}
+
+async function askForUninstallConfirmation() {
+    const answer = await askQuestion(`是否现在自动卸载 ${UPSTREAM_GLOBAL_PACKAGE}？[Y/n]: `);
+    return parseYesNo(answer, true);
+}
+
+function uninstallUpstreamPackage() {
+    try {
+        execSync(`npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`, {
+            stdio: "inherit",
+        });
+        return true;
+    } catch (err) {
+        return false;
+    }
+}
+
+async function main() {
+    const isGlobalInstall = process.env.npm_config_global === "true";
+    if (!isGlobalInstall) {
+        return;
+    }
+
+    if (process.env.LING_SKIP_UPSTREAM_CHECK === "1" || process.env.AG_KIT_SKIP_UPSTREAM_CHECK === "1") {
+        return;
+    }
+
+    const deps = readGlobalNpmDependencies();
+    if (!deps) {
+        return;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(deps, UPSTREAM_GLOBAL_PACKAGE)) {
+        return;
+    }
+
+    console.warn(`\n[warn] 检测到全局已安装上游英文版 ${UPSTREAM_GLOBAL_PACKAGE}`);
+    console.warn("[warn] 上游英文版与当前版本共用 `ag-kit` 兼容命令名，后安装者会覆盖该入口。");
+    console.warn("[warn] 为避免后续混淆，建议仅保留一个来源。\n");
+
+    if (!canPromptUser()) {
+        console.warn("[info] 当前环境不是交互式终端，无法确认是否自动卸载。");
+        console.warn(`[hint] 如需卸载，请手动执行: npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
+        console.warn("[info] 本次将继续安装；安装完成后正式命令请使用 `ling`。\n");
+        return;
+    }
+
+    const shouldUninstall = await askForUninstallConfirmation();
+
+    if (!shouldUninstall) {
+        console.warn(`[info] 已保留 ${UPSTREAM_GLOBAL_PACKAGE}，继续安装当前版本。`);
+        console.warn("[info] 结果说明：正式命令请使用 `ling`，旧 `ag-kit` 仅保留兼容入口。\n");
+        return;
+    }
+
+    console.warn(`\n[clean] 正在卸载 ${UPSTREAM_GLOBAL_PACKAGE} ...`);
+    const ok = uninstallUpstreamPackage();
+
+    if (ok) {
+        console.warn(`[ok] 已卸载 ${UPSTREAM_GLOBAL_PACKAGE}，继续安装当前版本。\n`);
+        return;
+    }
+
+    console.warn(`[error] 自动卸载 ${UPSTREAM_GLOBAL_PACKAGE} 失败，将继续安装当前版本。`);
+    console.warn("[info] 若需手动处理，请执行：");
+    console.warn(`   npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
+    console.warn("[info] 安装完成后，正式命令请使用 `ling`；旧 `ag-kit` 仅保留兼容入口。\n");
+}
+
+main().catch((err) => {
+    console.warn("[warn] postinstall 冲突检测出现异常，已跳过，不影响安装继续。");
+    if (err && err.message) {
+        console.warn(`   ${err.message}`);
+    }
+});

package/scripts/run-tests.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const ROOT_DIR = path.resolve(__dirname, "..");
+const TESTS_DIR = path.join(ROOT_DIR, "tests");
+
+function collectTestFiles(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...collectTestFiles(fullPath));
+            continue;
+        }
+
+        if (entry.isFile() && entry.name.endsWith(".test.js")) {
+            files.push(fullPath);
+        }
+    }
+
+    return files.sort();
+}
+
+function main() {
+    const testFiles = collectTestFiles(TESTS_DIR);
+    if (testFiles.length === 0) {
+        console.error("未找到测试文件");
+        process.exit(1);
+    }
+
+    const result = spawnSync(process.execPath, ["--test", ...testFiles], {
+        cwd: ROOT_DIR,
+        stdio: "inherit",
+    });
+
+    if (result.error) {
+        console.error(result.error.message);
+        process.exit(1);
+    }
+
+    process.exit(result.status || 0);
+}
+
+main();

package/tests/atomic-writer.test.js

@@ -0,0 +1,47 @@
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const AtomicWriter = require('../bin/utils/atomic-writer');
+
+describe('AtomicWriter', () => {
+    let workDir;
+    let sourceDir;
+    let targetDir;
+
+    beforeEach(() => {
+        workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'atomic-test-'));
+        sourceDir = path.join(workDir, 'source');
+        targetDir = path.join(workDir, 'target');
+        
+        fs.mkdirSync(sourceDir);
+        fs.writeFileSync(path.join(sourceDir, 'data.txt'), 'version 1');
+    });
+
+    afterEach(() => {
+        fs.rmSync(workDir, { recursive: true, force: true });
+    });
+
+    test('atomicCopyDir should copy directory when target does not exist', () => {
+        AtomicWriter.atomicCopyDir(sourceDir, targetDir);
+        
+        assert.ok(fs.existsSync(targetDir));
+        assert.strictEqual(fs.readFileSync(path.join(targetDir, 'data.txt'), 'utf8'), 'version 1');
+    });
+
+    test('atomicCopyDir should overwrite existing directory', () => {
+        // Setup initial target
+        fs.mkdirSync(targetDir);
+        fs.writeFileSync(path.join(targetDir, 'old.txt'), 'old data');
+        
+        // Prepare new source
+        fs.writeFileSync(path.join(sourceDir, 'data.txt'), 'version 2');
+
+        AtomicWriter.atomicCopyDir(sourceDir, targetDir);
+
+        assert.ok(fs.existsSync(targetDir));
+        assert.strictEqual(fs.readFileSync(path.join(targetDir, 'data.txt'), 'utf8'), 'version 2');
+        assert.ok(!fs.existsSync(path.join(targetDir, 'old.txt')), 'Old file should be gone');
+    });
+});