update-graft-inventory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Graft Inventory Skill

更新Graft清单操作指南

When to Activate

何时激活

Activate this skill when:

Adding new feature flags via SQL migrations
Removing or deprecating grafts
The graft-inventory CI check fails
You want to verify inventory matches production D1
After applying migrations that add grafts

在以下场景激活本操作：

通过SQL迁移添加新的功能标志
移除或弃用graft
graft-inventory CI检查失败
你需要验证清单与生产环境D1是否一致
在应用添加graft的迁移之后

Files Involved

涉及文件

File	Purpose
`.github/graft-inventory.json`	Source of truth for graft counts and metadata
`packages/engine/migrations/*.sql`	Migration files that define grafts
`packages/engine/src/lib/feature-flags/grafts.ts`	Type definitions ( `KnownGraftId` )
`docs/guides/adding-grafts-and-flags.md`	Developer guide

文件	用途
`.github/graft-inventory.json`	graft数量及元数据的权威来源
`packages/engine/migrations/*.sql`	定义graft的迁移文件
`packages/engine/src/lib/feature-flags/grafts.ts`	类型定义（ `KnownGraftId` ）
`docs/guides/adding-grafts-and-flags.md`	开发者指南

Inventory Structure

清单结构

The inventory tracks grafts with full metadata:

json

{
  "grafts": {
    "total": 10,
    "breakdown": {
      "platform": 8,
      "greenhouse": 2
    },
    "byType": {
      "boolean": 9,
      "number": 1
    }
  },
  "flags": [
    {
      "id": "fireside_mode",
      "name": "Fireside Mode",
      "type": "boolean",
      "greenhouseOnly": true,
      "migration": "040_fireside_scribe_grafts.sql",
      "description": "AI-assisted writing prompts"
    }
  ]
}

清单会跟踪包含完整元数据的graft：

json

{
  "grafts": {
    "total": 10,
    "breakdown": {
      "platform": 8,
      "greenhouse": 2
    },
    "byType": {
      "boolean": 9,
      "number": 1
    }
  },
  "flags": [
    {
      "id": "fireside_mode",
      "name": "Fireside Mode",
      "type": "boolean",
      "greenhouseOnly": true,
      "migration": "040_fireside_scribe_grafts.sql",
      "description": "AI-assisted writing prompts"
    }
  ]
}

Step-by-Step Process

分步流程

1. List Grafts from Migrations

1. 从迁移文件中列出Graft

bash

undefined

bash

undefined

Extract all flag IDs from migration INSERT statements

从迁移的INSERT语句中提取所有标志ID

grep -hoP "INSERT OR IGNORE INTO feature_flags.?VALUES\s(\s*'\K[a-z_]+" packages/engine/migrations/*.sql | sort -u

undefined

grep -hoP "INSERT OR IGNORE INTO feature_flags.?VALUES\s(\s*'\K[a-z_]+" packages/engine/migrations/*.sql | sort -u

undefined

2. Query Production D1

2. 查询生产环境D1数据库

bash

undefined

bash

undefined

Get actual flags from production database

从生产数据库获取实际的标志

npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;"

undefined

npx wrangler d1 execute grove-engine-db --remote --command="SELECT id, name, flag_type, greenhouse_only, enabled FROM feature_flags ORDER BY id;"

undefined

3. Compare with Inventory

3. 与清单进行对比

bash

undefined

bash

undefined

Read current inventory

读取当前清单

cat .github/graft-inventory.json | jq '.flags[].id' | sort

undefined

cat .github/graft-inventory.json | jq '.flags[].id' | sort

undefined

4. Identify Discrepancies

4. 识别差异

Look for:

New grafts: In migrations/D1 but not in inventory
Removed grafts: In inventory but not in D1
Changed metadata: Type, greenhouse_only, or description changed

查找以下情况：

新增graft：存在于迁移文件/D1中，但不在清单里
已移除graft：存在于清单里，但不在D1中
元数据变更：类型、greenhouse_only或描述发生变化

5. Update Inventory JSON

5. 更新清单JSON文件

Edit

.github/graft-inventory.json

Update counts:

json

"grafts": {
  "total": <new count>,
  "breakdown": {
    "platform": <non-greenhouse count>,
    "greenhouse": <greenhouse_only count>
  }
}

Add/remove flag entries:

json

"flags": [
  {
    "id": "new_flag_id",
    "name": "Human Readable Name",
    "type": "boolean",
    "greenhouseOnly": false,
    "migration": "XXX_migration_name.sql",
    "description": "What this flag controls"
  }
]

Update metadata:

json

"lastUpdated": "YYYY-MM-DD",
"lastAuditedBy": "claude/<context>"

编辑

.github/graft-inventory.json

：

更新计数：

json

"grafts": {
  "total": <new count>,
  "breakdown": {
    "platform": <non-greenhouse count>,
    "greenhouse": <greenhouse_only count>
  }
}

添加/移除标志条目：

json

"flags": [
  {
    "id": "new_flag_id",
    "name": "Human Readable Name",
    "type": "boolean",
    "greenhouseOnly": false,
    "migration": "XXX_migration_name.sql",
    "description": "What this flag controls"
  }
]

更新元数据：

json

"lastUpdated": "YYYY-MM-DD",
"lastAuditedBy": "claude/<context>"

6. Update KnownGraftId Type

6. 更新KnownGraftId类型

Edit

packages/engine/src/lib/feature-flags/grafts.ts

typescript

export type KnownGraftId =
  | "fireside_mode"
  | "scribe_mode"
  | "meadow_access"
  | "jxl_encoding"
  | "jxl_kill_switch"
  | "new_flag_id";  // Add new flag

编辑

packages/engine/src/lib/feature-flags/grafts.ts

：

typescript

export type KnownGraftId =
  | "fireside_mode"
  | "scribe_mode"
  | "meadow_access"
  | "jxl_encoding"
  | "jxl_kill_switch"
  | "new_flag_id";  // 添加新标志

7. Commit Changes

7. 提交变更

bash

git add .github/graft-inventory.json packages/engine/src/lib/feature-flags/grafts.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownGraftId type"

bash

git add .github/graft-inventory.json packages/engine/src/lib/feature-flags/grafts.ts
git commit -m "docs: update graft inventory

- Add <flag_id> to inventory
- Update total: X -> Y
- Update KnownGraftId type"

Quick Reference Commands

快速参考命令

bash

undefined

bash

undefined

Count grafts in migrations

统计迁移文件中的graft数量

grep -c "INSERT OR IGNORE INTO feature_flags" packages/engine/migrations/*.sql | awk -F: '{sum+=$2} END {print sum}'

List all flag IDs

列出所有标志ID

grep -hoP "INSERT OR IGNORE INTO feature_flags.?VALUES\s(\s*'\K[a-z_]+" packages/engine/migrations/*.sql | sort -u

Count greenhouse-only grafts

统计仅greenhouse的graft数量

npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) FROM feature_flags WHERE greenhouse_only = 1;"

Full flag details from production

从生产环境获取完整的标志详情

npx wrangler d1 execute grove-engine-db --remote --command="SELECT * FROM feature_flags ORDER BY id;"

Check which migrations haven't been applied

检查哪些迁移未被应用

Compare migration file flag IDs vs production D1 flag IDs

对比迁移文件中的标志ID与生产环境D1的标志ID

undefined

undefined

Adding a New Graft (Full Checklist)

添加新Graft的完整检查清单

When adding a new graft:

Create migration file:
```
packages/engine/migrations/XXX_name.sql
```

Apply migration:

npx wrangler d1 execute grove-engine-db --remote --file=...

Add to
```
KnownGraftId
```
type in
```
grafts.ts
```
Add entry to
```
.github/graft-inventory.json
```
flags array
Update inventory counts (total, breakdown.platform/greenhouse, byType)
Update
```
lastUpdated
```
and
```
lastAuditedBy
```
Commit all changes together

添加新graft时：

创建迁移文件：
```
packages/engine/migrations/XXX_name.sql
```

应用迁移：

npx wrangler d1 execute grove-engine-db --remote --file=...

在
```
grafts.ts
```
的
```
KnownGraftId
```
类型中添加新ID
在
```
.github/graft-inventory.json
```
的flags数组中添加条目
更新清单计数（total、breakdown.platform/greenhouse、byType）
更新
```
lastUpdated
```
和
```
lastAuditedBy
```
一起提交所有变更

Verifying Production Sync

验证与生产环境同步

After updating, verify production matches:

bash

undefined

更新完成后，验证生产环境是否匹配：

bash

undefined

Expected count

预期计数

jq '.grafts.total' .github/graft-inventory.json

Actual count in production

生产环境中的实际计数

npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) as count FROM feature_flags;"


If they don't match, migrations may need to be applied:

```bash

npx wrangler d1 execute grove-engine-db --remote --command="SELECT COUNT(*) as count FROM feature_flags;"


如果两者不匹配，可能需要应用迁移：

```bash

Apply a specific migration

应用特定迁移

npx wrangler d1 execute grove-engine-db --remote --file=packages/engine/migrations/XXX_name.sql

undefined

npx wrangler d1 execute grove-engine-db --remote --file=packages/engine/migrations/XXX_name.sql

undefined

CI Integration

CI集成

The

.github/workflows/graft-inventory.yml

workflow:

Runs on PRs touching
```
packages/engine/migrations/*.sql
```

Runs on PRs touching

packages/engine/src/lib/feature-flags/**

Parses migrations for INSERT statements
Compares count to inventory
Comments on PRs when there's a mismatch
Creates issues for drift on scheduled runs (Wednesdays)

When CI fails, run this skill to fix the mismatch.

.github/workflows/graft-inventory.yml

工作流：

在触及
```
packages/engine/migrations/*.sql
```
的PR上运行

在触及

packages/engine/src/lib/feature-flags/**

的PR上运行

解析迁移文件中的INSERT语句
将计数与清单进行对比
当存在不匹配时在PR上添加评论
在定期运行时（周三）创建关于差异的Issue

当CI检查失败时，执行本操作流程来修复不匹配问题。

Checklist

检查清单

Before finishing:

Production D1 graft count matches inventory
```
total
```
All flags in D1 have entries in inventory
```
flags
```
array
```
KnownGraftId
```
type includes all flag IDs
```
lastUpdated
```
date is today
Counts add up:
```
total = platform + greenhouse
```
Type breakdown is accurate
Changes committed with descriptive message

完成前确认：

生产环境D1的graft计数与清单中的
```
total
```
一致
D1中的所有标志在清单的
```
flags
```
数组中都有对应条目
```
KnownGraftId
```
类型包含所有标志ID
```
lastUpdated
```
日期为今天
计数相加正确：
```
total = platform + greenhouse
```
类型分类准确
已提交带有描述性信息的变更