maref 0.36.0rc0__tar.gz → 0.37.0.dev0__tar.gz

maref-0.37.0.dev0/.claude/skills/npm-signup-automation/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: npm-signup-automation
+description: >
+  通过 Playwright 自动化 npm 账号注册 + Token 生成 + 发布流程。
+  覆盖 Cloudflare 反爬绕过（系统 Chrome CDP 模式）、React SPA 表单交互、
+  2FA 绕过 Token 生成、scope 冲突处理等实战经验。
+---
+
+# npm 账号注册 + 发布自动化 Skill
+
+## 一、前置条件
+
+```bash
+# 安装 Playwright（仅需要 chromium）
+pip install playwright
+playwright install chromium
+
+# 启动系统 Chrome CDP（最可靠的 Cloudflare 绕过方式）
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-npm-tmp \
+  --remote-allow-origins=*
+```
+
+> `--remote-allow-origins=*` 是 CDP WebSocket 连接所必需的，否则会 403。
+
+---
+
+## 二、注册表单（npmjs.com/signup）
+
+| 字段 | DOM 选择器 | 说明 |
+|---|---|---|
+| 用户名 | `#signup_name` | **必须全小写**，建议含 `-org` 后缀 |
+| 邮箱 | `#signup_email` | 会公开在包元数据中 |
+| 密码 | `#signup_password` | 最少 10 字符 |
+| EULA | `#signup_eula-agreement` | 点击即可，label 绑定了事件 |
+| 提交 | `button:has-text("Create an Account")` | |
+
+> **经验**: 注册后邮箱验证是必要步骤，验证前无法 publish。验证 OTP 通常几分钟内送达。
+
+---
+
+## 三、Token 生成（关键难点）
+
+npm 已弃用 Classic Token。必须使用 **Granular Access Token**。
+
+### 3.1 页面结构
+
+表单 URL: `/settings/{username}/tokens/granular-access-tokens/new`
+
+| 字段 | 选择器 | 说明 |
+|---|---|---|
+| Token 名称 | `#create-gat_tokenName` | 唯一 |
+| 描述 | `#create-gat_tokenDescription` | 可选 |
+| Bypass 2FA | `#create-gat_bypass2FA` | **点击 label**，不要直接点 checkbox |
+| Packages 权限 | 下拉菜单 `summary` 第 1 个 | 点击后选 "Read and write" |
+| 包范围 | `#packagesAll` / `#packagesAndScopesSome` | 选 All packages |
+| Organizations | 下拉菜单 `summary` 第 2 个 | 用户账号设为 "No access" |
+| 过期 | 下拉菜单 `summary` 第 3 个 | 默认 7 天（可改 30/90 天） |
+| 提交 | `button:has-text("Generate token")` | |
+
+### 3.2 ⚠️ Bypass 2FA 复选框陷阱
+
+**这是最常见的坑**。npm 使用 React SPA，直接操作 checkbox 不会更新组件状态：
+
+```python
+# ❌ 不行：Playwright .check() 报错 "did not change its state"
+page.locator('#create-gat_bypass2FA').check()
+
+# ❌ 不行：JS 原生 click 不触发 React 变更
+page.evaluate("document.getElementById('create-gat_bypass2FA').click()")
+
+# ❌ 不行：JS 修改 checked + dispatchEvent 不代表表单提交时会发送正确值
+# 这会导致 POST 数据中 bypass2FA=false（因为 React 未更新内部状态）
+
+# ✅ 正确：点击 label 元素（React 监听了 label 的 click 事件）
+page.locator('label[for="create-gat_bypass2FA"]').click()
+# 此时 POST 数据中 bypass2FA=true
+```
+
+> **验证方法**: 用 Playwright 拦截 POST 请求，检查 `request.post_data` 中的 `bypass2FA` 字段。
+> 生成后在 Token 详情页检查 `#gat-details_bypass2FA.checked`。
+
+### 3.3 权限下拉菜单操作
+
+下拉菜单使用 `details + summary` + `role="menuitemcheckbox"` 组件：
+
+```python
+page.evaluate("""
+() => {
+    const summaries = document.querySelectorAll('summary');
+    if (summaries[0]) summaries[0].click();  # 打开 packages 下拉
+    return new Promise((resolve) => {
+        setTimeout(() => {
+            const buttons = document.querySelectorAll('button[role="menuitemcheckbox"]');
+            for (const btn of buttons) {
+                const span = btn.querySelector('span');
+                if (span && span.textContent.trim() === 'Read and write') {
+                    btn.click();
+                    resolve();
+                    return;
+                }
+            }
+            resolve();
+        }, 200);
+    });
+}
+""")
+```
+
+---
+
+## 四、发布到 npm
+
+### 4.1 配置镜像问题
+
+全局 `.npmrc` 可能指向中国镜像（`registry.npmmirror.com`），**必须显式覆盖**：
+
+```bash
+# 使用 token 发布（推荐）
+echo "//registry.npmjs.org/:_authToken=npm_xxxxx" > /tmp/.npmrc-publish
+npm publish --registry=https://registry.npmjs.org/ --access public --userconfig=/tmp/.npmrc-publish
+
+# 或者配置环境变量
+NODE_AUTH_TOKEN=npm_xxxxx npm publish --registry=https://registry.npmjs.org/ --access public
+```
+
+### 4.2 2FA 注意事项
+
+- 如果发布报错 `Two-factor authentication required`，说明 token 的 Bypass 2FA 未正确设置
+- 验证方式：检查 POST 数据中 `bypass2FA` 是否为 `true`
+- npm 从 2026 年 8 月起限制 bypass 2FA token 的账户变更，2027 年 1 月起限制直接发布
+
+---
+
+## 五、Scope 冲突处理
+
+| 情况 | 处理 |
+|---|---|
+| 想要的 scope 已被注册（如 `@maref`） | 用 `@username/package` 格式，如 `@maref-org/sdk` |
+| Scope 对应的 org 名不可用 | 尝试 `-org`、`-io`、`_io` 等后缀 |
+| 用户名和 scope 不一致 | 发布后可在 npm 页面创建组织来转移 scope，但最简单的是直接用用户名 scope |
+
+> npm 不允许在用户名/组织名之外的其他 scope 下发布包。`@maref/sdk` 不可用是因为 `maref` 用户/组织已存在。
+
+---
+
+## 六、完整自动化流程示例
+
+```python
+from playwright.sync_api import sync_playwright
+import json, time, re
+
+with sync_playwright() as p:
+    # Step 1: 连接已启动的 Chrome CDP
+    browser = p.chromium.connect_over_cdp("http://localhost:9222")
+    page = browser.contexts[0].pages[0]
+    
+    # Step 2: 填写表单
+    page.locator('#create-gat_tokenName').fill("my-publish-token")
+    
+    # Step 3: 点击 bypass 2FA 的 label（不是 checkbox）
+    page.locator('label[for="create-gat_bypass2FA"]').click()
+    
+    # Step 4: 设置权限
+    # (见第三节代码)
+    
+    # Step 5: 捕获 POST 数据验证
+    post_data = []
+    def on_request(req):
+        if 'new-gat' in req.url and req.method == 'POST':
+            post_data.append(req.post_data)
+    page.on('request', on_request)
+    
+    # Step 6: 生成 token
+    page.locator('button:has-text("Generate token")').click()
+    time.sleep(3)
+    
+    # Step 7: 读取 token
+    body_text = page.inner_text('body')
+    tokens = re.findall(r'npm_[a-zA-Z0-9_]{36,}', body_text)
+    if tokens:
+        print(f"Token: {tokens[0]}")
+```
+
+---
+
+## 七、常见错误速查
+
+| 错误 | 原因 | 修复 |
+|---|---|---|
+| `Name must be lowercase` | 用户名含大写 | 全小写 |
+| `username is already taken` | 用户名占用 | 尝试 `xxx-org` / `xxx_io` |
+| `organization name X is not available` | scope 被占用 | 改用 `@username/package` |
+| `Checkbox did not change its state` | React 未响应 | **点击 label** 而非 checkbox |
+| `Two-factor authentication required` | bypass 2FA 未生效 | 验证 POST 数据确认 |
+| `403 Forbidden` | 权限不足 / 2FA | 检查 token scope + bypass 2FA |
+| `Duplicate token names are not allowed` | token 名已存在 | 加后缀如 `-v2` |
+| `Route not found!` | URL 路径错误 | Classic Token URL 可能已失效 |
+| CDP WebSocket `403 Forbidden` | 缺 `--remote-allow-origins` | Chrome 启动参数加该 flag |

maref-0.37.0.dev0/.evolution_daemon_state.json

@@ -0,0 +1,5 @@
+{
+  "last_run": "2026-07-11T02:59:57.440567+00:00",
+  "total_runs": 130,
+  "failed_runs": 0
+}

maref-0.37.0.dev0/.github/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md — MAREF Coding Agent Configuration
+
+> **M**ulti-**A**gent **R**ecursive **E**volution **F**ramework  
+> Version: 0.36.0-rc | License: Apache 2.0
+
+This file defines how AI coding agents should interact with this repository.
+
+## 1. Role & Purpose
+
+You are a senior developer contributing to MAREF — an Agent Governance OS. Your primary responsibilities:
+
+- Maintain code quality, security, and governance standards
+- Follow the project's I Ching-based governance model
+- Preserve backward compatibility where possible
+- Always write testable, observable code
+
+## 2. Key Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Python | 3.10+, pytest, ruff, mypy strict |
+| Frontend | React 19, TypeScript, Vite, TailwindCSS |
+| Desktop | Tauri 2.x, Rust |
+| CI/CD | GitHub Actions, CodeQL, SonarCloud |
+| Security | Bandit, Semgrep, TruffleHog, pip-audit |
+| Formal | TLA+ (TLC model checker) |
+
+## 3. Coding Standards
+
+### Python
+
+```bash
+# Must pass before any commit
+ruff check src/
+ruff format --check src/
+mypy src/
+```
+
+- Use type hints on all function signatures
+- Follow PEP 8 conventions
+- No `print()` in production code — use `structlog`
+- All public APIs must have docstrings
+
+### TypeScript / React
+
+```bash
+# In gui/ directory
+pnpm lint
+pnpm typecheck
+pnpm build
+```
+
+- Use TypeScript strict mode
+- Prefer function components with hooks
+- Use TailwindCSS for styling
+
+## 4. Commit Convention
+
+```
+type(scope): description
+
+feat:     new feature
+fix:      bug fix
+chore:    maintenance, deps, config
+docs:     documentation
+test:     tests
+refactor: code restructuring
+style:    formatting (ruff/prettier)
+```
+
+## 5. PR Requirements
+
+- All CI checks must pass
+- At least 1 approving review
+- No new ruff/mypy errors
+- Tests must include coverage for changes
+- D1 gate must pass for release branches

maref-0.37.0.dev0/.github/actions/maref-ci-governance/action.yml

@@ -0,0 +1,127 @@
+name: "MAREF CI Governance"
+description: >
+  Enforce MAREF governance policies in CI pipelines. Scans PR changes and
+  workflow commands against the MAREF sidecar to detect policy violations
+  before they reach production.
+
+inputs:
+  sidecar-url:
+    description: "MAREF sidecar URL"
+    required: false
+    default: "http://localhost:8000"
+
+  mode:
+    description: "Governance mode: enforcing (fail on violation), advisory (warn only), logging (skip)"
+    required: false
+    default: "advisory"
+
+  fail-closed:
+    description: "Fail closed when sidecar is unreachable"
+    required: false
+    default: "true"
+
+  github-token:
+    description: "GitHub token for PR API access"
+    required: false
+    default: ${{ github.token }}
+
+runs:
+  using: "composite"
+  steps:
+    - id: setup-node
+      uses: actions/setup-node@v4
+      with:
+        node-version: "22"
+
+    - id: install
+      shell: bash
+      run: |
+        npm install -g @maref-org/sdk
+
+    - id: scan-pr
+      shell: bash
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "🔍 Scanning PR changes for MAREF policy violations..."
+        echo "Mode: ${{ inputs.mode }}"
+        echo "Sidecar: ${{ inputs.sidecar-url }}"
+
+        PR_FILES=$(gh pr view ${{ github.event.pull_request.number }} \
+          --json files --jq '.files[].path' 2>/dev/null || echo "")
+
+        if [ -z "$PR_FILES" ]; then
+          echo "✅ No file changes detected in PR"
+          exit 0
+        fi
+
+        VIOLATIONS=0
+        for file in $PR_FILES; do
+          echo "  Checking: $file"
+
+          # Skip safe file patterns
+          case "$file" in
+            *.md|*.txt|*.json|*.yml|*.yaml|*.svg|*.png|*.jpg|*.jpeg|*.gif|*.lock)
+              echo "    ⏭️  Skipped (non-executable)"
+              continue
+              ;;
+          esac
+
+          # Check with MAREF sidecar
+          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "${{ inputs.sidecar-url }}/api/v1/check-before-write" \
+            -H "Content-Type: application/json" \
+            -d "{\"file_path\": \"$file\", \"actor\": \"ci-governance\", \"session_id\": \"${{ github.run_id }}\"}" 2>/dev/null)
+
+          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+          BODY=$(echo "$RESPONSE" | head -n -1)
+
+          if [ "$HTTP_CODE" != "200" ]; then
+            if [ "${{ inputs.fail-closed }}" = "true" ] && [ "${{ inputs.mode }}" = "enforcing" ]; then
+              echo "    ❌ Sidecar unreachable (fail-closed)"
+              VIOLATIONS=$((VIOLATIONS + 1))
+            else
+              echo "    ⚠️  Sidecar unreachable (fail-open, skipping)"
+            fi
+            continue
+          fi
+
+          VERDICT=$(echo "$BODY" | jq -r '.verdict // "allow"')
+          if [ "$VERDICT" = "block" ]; then
+            REASON=$(echo "$BODY" | jq -r '.reason // "Policy violation"')
+            echo "    ❌ BLOCKED: $REASON"
+            VIOLATIONS=$((VIOLATIONS + 1))
+          else
+            echo "    ✅ Allowed"
+          fi
+        done
+
+        echo ""
+        if [ $VIOLATIONS -gt 0 ]; then
+          echo "❌ Found $VIOLATIONS policy violation(s)"
+          if [ "${{ inputs.mode }}" = "enforcing" ]; then
+            exit 1
+          else
+            echo "⚠️  Advisory mode — not failing CI"
+          fi
+        else
+          echo "✅ No policy violations detected"
+        fi
+
+      env:
+        GITHUB_TOKEN: ${{ inputs.github-token }}
+
+    - id: summary
+      shell: bash
+      run: |
+        echo "### MAREF CI Governance Summary" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "| Setting | Value |" >> $GITHUB_STEP_SUMMARY
+        echo "|---------|-------|" >> $GITHUB_STEP_SUMMARY
+        echo "| Mode | ${{ inputs.mode }} |" >> $GITHUB_STEP_SUMMARY
+        echo "| Sidecar | ${{ inputs.sidecar-url }} |" >> $GITHUB_STEP_SUMMARY
+        echo "| Fail-closed | ${{ inputs.fail-closed }} |" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "_MAREF CI Governance scan complete._" >> $GITHUB_STEP_SUMMARY
+
+branding:
+  icon: "shield"
+  color: "blue"

maref-0.37.0.dev0/.github/workflows/ci.yml

@@ -0,0 +1,83 @@
+name: MAREF CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev,sidecar,otel,a2a,orchestration,identity]"
+      - name: Ruff lint
+        run: ruff check src/maref src/maref_lite
+      - name: Ruff format check
+        run: ruff format --check src/maref src/maref_lite
+      - name: Mypy type check
+        run: mypy src/maref src/maref_lite
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev,sidecar,otel,a2a,orchestration,identity]"
+      - name: Run unit tests
+        run: |
+          coverage run -m pytest tests/ -x -q --timeout=120 -m "not integration and not chaos and not benchmark" --ignore=tests/maref/compliance
+      - name: Validate mock consistency
+        if: github.event_name != 'pull_request'
+        run: python -c "from maref.testing.mock_validator import MockValidator; v=MockValidator(schema_dir=Path('vault/schemas'), mock_dir=Path('vault/mocks')); errors=v.validate_all(); assert not errors, f'Mock mismatch: {errors}'"
+        continue-on-error: true
+      - name: Coverage report
+        run: coverage report --fail-under=30
+
+  security:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev,sidecar,otel,a2a]"
+      - name: Bandit SAST
+        run: bandit -r src/ -c pyproject.toml || true
+      - name: pip-audit
+        run: pip-audit
+      - name: TruffleHog Secret Scan
+        run: |
+          pip install trufflehog
+          trufflehog filesystem . --config .trufflehog.yaml --since 2026-01-01
+
+  crypto-test:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev,sidecar,otel,a2a,orchestration,identity]"
+      - name: Run cryptography tests
+        run: |
+          pytest tests/test_crypto.py -v

maref-0.37.0.dev0/.github/workflows/formal-verify.yml

@@ -0,0 +1,41 @@
+name: Formal Verification
+
+on:
+  push:
+    paths:
+      - 'src/formal/**'
+      - 'src/maref/governance/**'
+      - 'src/maref/integration/test_platform/**'
+      - 'src/maref/security/steg_sanitizer.py'
+  pull_request:
+    paths:
+      - 'src/formal/**'
+      - 'src/maref/governance/**'
+      - 'src/maref/integration/test_platform/**'
+      - 'src/maref/security/steg_sanitizer.py'
+  workflow_dispatch:
+
+jobs:
+  tla-verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+      - name: Setup TLA+
+        run: |
+          wget -q https://github.com/tlaplus/tlaplus/releases/download/v1.4.5/tla2tools.jar -O /tmp/tla2tools.jar
+      - name: Verify Gray Code FSM
+        run: |
+          java -cp /tmp/tla2tools.jar tlc2.TLC src/formal/MarefLite.tla -config src/formal/MarefLiteMC.cfg
+      - name: Verify Consensus
+        run: |
+          java -cp /tmp/tla2tools.jar tlc2.TLC src/formal/MAREF_Consensus.tla -config src/formal/MAREF_ConsensusMC.cfg
+      - name: Verify Constitutional Red Lines (RL-001 ~ RL-005)
+        run: |
+          java -cp /tmp/tla2tools.jar tlc2.TLC -config src/formal/MAREF_ConstitutionalRedLinesMC.cfg src/formal/MAREF_ConstitutionalRedLines.tla
+      - name: Verify Test Integration Theorems (含 StenoDetectionComplete)
+        run: |
+          java -cp /tmp/tla2tools.jar tlc2.TLC src/formal/MAREF_TestIntegration.tla -config src/formal/MAREF_TestIntegrationMC.cfg

maref-0.37.0.dev0/.github/workflows/frontend-security.yml

@@ -0,0 +1,44 @@
+name: Frontend Security Audit
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'gui/**'
+      - '.github/workflows/frontend-security.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'gui/**'
+      - '.github/workflows/frontend-security.yml'
+  schedule:
+    - cron: '0 9 * * 1'
+
+jobs:
+  pnpm-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10.33.2
+
+      - name: Install dependencies
+        working-directory: ./gui
+        run: pnpm install --frozen-lockfile
+
+      - name: Run pnpm audit
+        working-directory: ./gui
+        run: pnpm audit --audit-level=high
+
+      - name: Run ESLint security checks
+        working-directory: ./gui
+        run: pnpm lint
+        continue-on-error: true

maref-0.37.0.dev0/.github/workflows/maref-ci-governance-example.yml

@@ -0,0 +1,18 @@
+name: MAREF CI Governance (example)
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  governance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: MAREF CI Governance Scan
+        uses: ./.github/actions/maref-ci-governance
+        with:
+          sidecar-url: "http://localhost:8000"
+          mode: "advisory"
+          fail-closed: "false"

maref-0.37.0.dev0/.github/workflows/mcp-governance-publish.yml

@@ -0,0 +1,52 @@
+name: Publish @maref-org/mcp-governance to npm
+
+on:
+  push:
+    tags:
+      - "mcp-governance-v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    defaults:
+      run:
+        working-directory: mcp/governance-server
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Check package content
+        run: |
+          echo "=== Package content ==="
+          npx pkgfiles --list 2>/dev/null || ls -la dist/
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "@maref-org/mcp-governance ${{ github.ref_name }}"
+          body_path: mcp/governance-server/CHANGELOG.md
+          prerelease: ${{ contains(github.ref_name, '-rc') }}
+        continue-on-error: true