cli-mergeguard 7.0.1

package/README.md

@@ -0,0 +1,11 @@
+# cli-mergeguard
+
+从 CLI.Tax 安装并运行 MergeGuard 技能：智能合并守卫——快照分支+预演+验证式合并+规则衰减防护。
+
+```bash
+npx cli-mergeguard@latest install
+```
+
+Source: https://github.com/88208555/MergeGuard-clitax.git
+
+`mergeguard.skill.request/1.0` 协议，端点 `https://cli.tax/Mm7GnPqR2v`。

package/cli.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { dispatchOfficialSkillCli, runIntakeHandshake } from './installer.mjs'
+
+const INTAKE_QUESTIONS = [
+  { id: 'repoType', prompt: 'Repository type: git, none (no version control), or snapshot (MergeGuard snapshot mode)?', required: true, example: 'snapshot' },
+  { id: 'riskLevel', prompt: 'Risk level: low, medium, or high?', required: true, example: 'medium' },
+  { id: 'baselineBranch', prompt: 'Baseline branch name (default: main)?', required: false, example: 'main' },
+]
+
+await dispatchOfficialSkillCli({
+  packageRoot: dirname(fileURLToPath(import.meta.url)),
+  runCommand: (context) => runIntakeHandshake(context, {
+    questions: INTAKE_QUESTIONS,
+    outputFile: 'MERGGUARD-REQUIREMENTS.json',
+    afterCapabilities(output) {
+      const instruction = output.nextStep?.instruction
+      if (typeof instruction === 'string' && instruction.trim()) console.log(instruction)
+    },
+  }),
+})

package/installer.mjs

@@ -0,0 +1,241 @@
+/**
+ * 五个官方技能共用这一份安装器。packages/*-cli/installer.mjs 必须与本文件字节一致。
+ * 禁止第二套超时、第二套版本来源、第二套 bin 名。
+ */
+import { copyFile, mkdir, writeFile } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { stdin, stdout } from 'node:process'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+
+export const LOOKUP_TIMEOUT_MS = 8000
+export const CALL_TIMEOUT_MS = 120_000
+const INSTALL_META = 'install-meta.json'
+
+function asObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`)
+  }
+  return value
+}
+
+function requiredString(value, label) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) throw new Error(`${label} is required`)
+  return text
+}
+
+export function loadOfficialSkillContext(packageRoot) {
+  const pkg = asObject(JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')), 'package.json')
+  const skill = asObject(JSON.parse(readFileSync(join(packageRoot, 'skill/skill.json'), 'utf8')), 'skill.json')
+  const npmName = requiredString(pkg.name, 'package.json name')
+  const packageVersion = requiredString(pkg.version, 'package.json version')
+  const displayName = requiredString(skill.displayName, 'skill.json displayName')
+  const skillName = requiredString(skill.name, 'skill.json name')
+  const schemaVersion = requiredString(skill.schemaVersion, 'skill.json schemaVersion')
+  const endpoint = requiredString(skill.endpoint, 'skill.json endpoint')
+  const skillVersion = requiredString(skill.version, 'skill.json version')
+  const runtimeCode = requiredString(endpoint.replace(/^https:\/\/cli\.tax\//, ''), 'runtime code')
+  if (!/^[A-Za-z0-9]{10}$/.test(runtimeCode)) {
+    throw new Error(`skill.json endpoint must be https://cli.tax/{10-char-code}: ${endpoint}`)
+  }
+  if (skillVersion.replace(/^v/i, '') !== packageVersion.replace(/^v/i, '')) {
+    throw new Error(`skill.json ${skillVersion} must match package.json ${packageVersion}`)
+  }
+  return {
+    packageRoot,
+    npmName,
+    packageVersion,
+    displayName,
+    skillName,
+    schemaVersion,
+    endpoint,
+    skillVersion,
+    runtimeCode,
+    latestEndpoint: `https://cli.tax/api/public/skills/${runtimeCode}`,
+    skillDir: join(packageRoot, 'skill'),
+  }
+}
+
+export function readInstallMeta(target) {
+  const path = join(target, INSTALL_META)
+  if (!existsSync(path)) return null
+  return asObject(JSON.parse(readFileSync(path, 'utf8')), INSTALL_META)
+}
+
+export function installTarget(skillName, explicit) {
+  if (explicit) return resolve(explicit)
+  const codexHome = process.env.CODEX_HOME?.trim()
+  if (codexHome) return join(codexHome, 'skills', skillName)
+  return join(process.cwd(), '.codex', 'skills', skillName)
+}
+
+export async function fetchLatestVersion(context) {
+  const response = await fetch(context.latestEndpoint, { signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) })
+  if (!response.ok) throw new Error(`cli.tax skill lookup failed: HTTP ${response.status}`)
+  const data = asObject(await response.json(), 'cli.tax skill lookup')
+  return {
+    version: requiredString(data.version, 'cli.tax skill lookup version'),
+    displayName: requiredString(data.displayName, 'cli.tax skill lookup displayName'),
+  }
+}
+
+export async function callOfficialSkill(context, operation, input) {
+  const requestId = `${context.npmName}-${Date.now()}`
+  const response = await fetch(context.endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      input: {
+        schemaVersion: context.schemaVersion,
+        requestId,
+        operation,
+        input,
+      },
+    }),
+    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+  })
+  let payload
+  try {
+    payload = await response.json()
+  } catch {
+    throw new Error(`${context.displayName} ${operation} failed: non-JSON response (HTTP ${response.status}). Check ${context.endpoint}.`)
+  }
+  if (!response.ok || payload?.ok !== true) {
+    const message = payload?.error?.message
+    if (typeof message !== 'string' || !message.trim()) {
+      throw new Error(`${context.displayName} ${operation} failed: HTTP ${response.status}`)
+    }
+    throw new Error(`${context.displayName} ${operation} failed: ${message}`)
+  }
+  return payload
+}
+
+export async function installOfficialSkill(context, explicit) {
+  const target = installTarget(context.skillName, explicit)
+  await mkdir(target, { recursive: true })
+  const previous = readInstallMeta(target)
+  await copyFile(join(context.skillDir, 'SKILL.md'), join(target, 'SKILL.md'))
+  await copyFile(join(context.skillDir, 'skill.json'), join(target, 'skill.json'))
+  const installed = asObject(JSON.parse(readFileSync(join(target, 'skill.json'), 'utf8')), 'installed skill.json')
+  const installedVersion = requiredString(installed.version, 'installed skill.json version')
+  await writeFile(join(target, INSTALL_META), `${JSON.stringify({
+    source: context.runtimeCode,
+    slug: context.skillName,
+    version: installedVersion,
+    packageVersion: context.packageVersion,
+    endpoint: context.endpoint,
+    installedAt: new Date().toISOString(),
+  }, null, 2)}\n`)
+  if (previous?.version && previous.version !== installedVersion) {
+    console.log(`${context.displayName} skill updated: ${target}`)
+    console.log(`  ${previous.version} → ${installedVersion}`)
+  } else {
+    console.log(`${context.displayName} skill installed: ${target} (${installedVersion})`)
+  }
+  console.log('Next: return to your IDE and state the goal. The agent reads the installed SKILL.md.')
+}
+
+export async function checkOfficialSkill(context, explicit) {
+  const target = installTarget(context.skillName, explicit)
+  const current = readInstallMeta(target)
+  if (!current) {
+    console.log(`${context.displayName} skill is not installed. Run: npx ${context.npmName}@latest install`)
+    process.exitCode = 1
+    return
+  }
+  const installedVersion = requiredString(current.version, 'install-meta.json version')
+  const packageVersion = requiredString(current.packageVersion, 'install-meta.json packageVersion')
+  console.log(`Installed: ${installedVersion} (package ${packageVersion})`)
+  const latest = await fetchLatestVersion(context)
+  console.log(`Latest on cli.tax: ${latest.version}`)
+  if (installedVersion === latest.version) {
+    console.log('Up to date.')
+    return
+  }
+  console.log(`Update available: ${installedVersion} → ${latest.version}`)
+  console.log(`Run: npx ${context.npmName}@latest install`)
+  process.exitCode = 1
+}
+
+export function defaultUsage(context, extraLines) {
+  const lines = [
+    `${context.npmName} — install and run the ${context.displayName} skill from CLI.Tax`,
+    '',
+    'Usage:',
+    `  npx ${context.npmName}@latest install [directory]`,
+    `      Install the ${context.displayName} skill for the current IDE.`,
+    `  npx ${context.npmName}@latest check [directory]`,
+    '      Check whether the installed skill has a newer version.',
+    `  npx ${context.npmName}@latest run`,
+    '      Run the skill handshake: discover capabilities and collect intake answers.',
+    '',
+    `Endpoint: ${context.endpoint}`,
+  ]
+  if (extraLines?.length) lines.push('', ...extraLines)
+  return lines.join('\n')
+}
+
+export async function runIntakeHandshake(context, spec) {
+  const capabilities = await callOfficialSkill(context, 'capabilities', {})
+  const output = capabilities.output && typeof capabilities.output === 'object' ? capabilities.output : {}
+  const skill = output.skill && typeof output.skill === 'object' ? output.skill : {}
+  const version = typeof skill.version === 'string' && skill.version.trim()
+    ? skill.version.trim()
+    : context.skillVersion
+  console.log(`${context.displayName} ${version}`)
+  if (typeof spec.afterCapabilities === 'function') spec.afterCapabilities(output)
+  const readline = createInterface({ input: stdin, output: stdout })
+  const answers = []
+  try {
+    for (const question of spec.questions) {
+      const requiredMark = question.required ? ' (required)' : ''
+      console.log(`\n${question.prompt}${requiredMark}`)
+      console.log(`Example: ${question.example}`)
+      for (;;) {
+        const answer = (await readline.question('> ')).trim()
+        if (answer) {
+          answers.push({ id: question.id, prompt: question.prompt, answer })
+          break
+        }
+        if (!question.required) break
+        console.log('This question is required. Please answer before continuing.')
+      }
+    }
+  } finally {
+    readline.close()
+  }
+  const target = join(process.cwd(), spec.outputFile)
+  await writeFile(target, `${JSON.stringify({
+    schemaVersion: context.schemaVersion,
+    endpoint: context.endpoint,
+    createdAt: new Date().toISOString(),
+    answers,
+  }, null, 2)}\n`)
+  console.log(`\nRequirements saved: ${target}`)
+  console.log('Next: continue in your IDE agent with this file.')
+}
+
+export async function dispatchOfficialSkillCli(options) {
+  const packageRoot = options.packageRoot ?? dirname(fileURLToPath(options.importMetaUrl))
+  const context = loadOfficialSkillContext(packageRoot)
+  const args = process.argv.slice(2)
+  const command = args[0] ?? 'help'
+  const argument = args[1]
+  try {
+    if (command === 'install') await installOfficialSkill(context, argument)
+    else if (command === 'check') await checkOfficialSkill(context, argument)
+    else if (command === 'run') await options.runCommand(context)
+    else if (command === 'help' || command === '--help' || command === '-h') {
+      console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
+    } else {
+      console.error(`Unknown command: ${command}`)
+      console.log(options.usage ? options.usage(context) : defaultUsage(context, options.extraUsageLines))
+      process.exitCode = 1
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error)
+    process.exitCode = 1
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "bin": {
+    "cli-mergeguard": "./cli.mjs"
+  },
+  "description": "MergeGuard skill installer for CLI.Tax: smart merge guard with snapshot branches, verified merge, and rule decay protection.",
+  "files": [
+    "cli.mjs",
+    "installer.mjs",
+    "README.md",
+    "skill/SKILL.md",
+    "skill/skill.json"
+  ],
+  "license": "UNLICENSED",
+  "name": "cli-mergeguard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/88208555/MergeGuard-clitax.git"
+  },
+  "type": "module",
+  "version": "7.0.1"
+}

package/skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mergeguard
+description: '智能合并守卫：快照分支+预演+验证式合并+规则衰减防护，解决全球 IDE 分支合并难题。'
+---
+
+# MergeGuard
+
+智能合并守卫——解决分支合并难题。
+
+## 三条铁律
+
+1. **合并不破坏**：合并前自动快照，全程隔离区进行，验证通过才落盘，一键回滚
+2. **AI 提议、测试裁决**：冲突方案可由模型生成，但必须通过测试验证才算数
+3. **小白可用**：零 git 心智的"快照分支"模式，全程向导式
+
+## 分层合并策略
+
+- **L1 文本层**：行级三方合并（兜底）
+- **L2 结构层**：AST 级/JSON 键路径级/公式图节点级合并（主力）
+- **L3 意图层**：AI 分析冲突意图 + 生成分辨率提案
+
+## 操作目录（14 个）
+
+| 操作 | 说明 |
+|------|------|
+| capabilities / help | 能力发现 + JSON Schema |
+| intake | 收集仓库形态/风险等级/基线 |
+| branch-create | 创建快照分支 |
+| branch-list | 列出所有分支 |
+| branch-switch | 切换当前分支 |
+| diff-report | 版本间结构化差异 |
+| preflight | 合并预演（冲突分级） |
+| resolve-propose | AI 冲突分辨率提案 |
+| merge-verified | 验证式合并（三道验证+落盘/拒绝） |
+| rollback | 一键回滚到合并前快照 |
+| ledger-query | 变更台账/审计查询 |
+| ruleguard-scan | 规则衰减扫描 |
+| ruleguard-compile | 规则编译 |
+
+## 规则衰减防护（RuleGuard）
+
+内置规则：no-inline-style / no-hardcode-color / no-eval / no-debug / no-magic-number
+三层防护：规则编译 → 写入时拦截 → 跨分支规则一致性
+
+## 验证式合并流程
+
+```
+合并候选（隔离区）
+  ↓
+① 结构效验：语法可解析、引用闭合
+② 黄金基准：全量回归测试
+③ 冒烟执行：沙箱跑通黄金路径
+  ↓
+全绿 → 落盘 + 更新台账
+任一红 → 拒绝落盘 + AI 修复提案
+```
+
+## 与技能链集成
+
+- aimlock：快照基础设施复用，合并须过 mutate-gate
+- blueprint：蓝图 IR 节点级合并
+- calctool：公式图节点级合并 + 基准数字对账
+- swarm：大合并任务拆单
+- Validator：三道验证裁剪复用

package/skill/skill.json

@@ -0,0 +1,10 @@
+{
+  "description": "MergeGuard 是智能合并守卫——解决全球 IDE 二十年未解好的分支合并难题。三条铁律：合并不破坏（快照隔离+一键回滚）、AI 提议测试裁决（模型无裁判权）、小白可用（零 git 心智向导）。分层合并策略：L1 文本层兜底 + L2 结构层主力（AST/JSON/公式图节点级合并）+ L3 意图层 AI 增强。验证式合并：隔离区执行三道验证（结构效验+黄金基准+冒烟），全绿才落盘。规则衰减防护：内置规则编译器+写入时拦截+跨分支规则一致性。调用顺序为 capabilities、intake、branch-create、preflight、merge-verified。合并不崩、崩了能回、伪冲突自动识别、静默坏合必拦截。本技能面向真实交付：每一步都有输入、规则与失败面，禁止把加载中、超时或未知状态当成空成功。调用前必须先走 capabilities，再按 nextStep 前进；必填项未回答不得进入下一操作。日志只保存必要元数据，密钥不得写入公开页面。",
+  "displayName": "MergeGuard",
+  "endpoint": "https://cli.tax/Mm7GnPqR2v",
+  "method": "POST",
+  "name": "mergeguard",
+  "schemaVersion": "mergeguard.skill.request/1.0",
+  "type": "Skill",
+  "version": "v7.0.1"
+}