@ghfs/cli 0.0.1 → 0.0.3

package/README.md

@@ -19,9 +19,10 @@ It will sync the open issues and pull requests to the local filesystem under `.g
 
 ```txt
 .ghfs/
-  repo.json  # repository basic information
-  issues.md  # index of fetched issues
-  pulls.md   # index of fetched pull requests
+  repo.json   # repository basic information
+  issues.md   # index of fetched issues
+  pulls.md    # index of fetched pull requests
+  execute.md  # queued operations
   issues/
     00134-some-bug.md
     closed/
@@ -35,22 +36,53 @@ It will sync the open issues and pull requests to the local filesystem under `.g
 
 Then you can view them offline, or ask your local agent to summarize them for you.
 
-## CLI feedback
+## Execute operations
 
-`ghfs` now provides stage-based sync feedback.
+`ghfs` also allows you to take actions on the issues and pull requests in batch.
 
-- In interactive terminals (TTY), `ghfs` uses rich progress indicators.
-- In CI or piped output, `ghfs` prints deterministic plain-text progress lines.
-- `ghfs sync --full` bypasses metadata early-return and runs full pagination.
+`ghfs execute` merges operations from multiple sources:
 
-`ghfs status` now also includes diagnostics from the latest sync run (duration, request count, counters, and stage timings) from `.ghfs/.sync.json`.
+1. `execute.md` (human-friendly commands)
+2. `per-issue` markdown frontmatter changes (from `.ghfs/issues/**/*.md` and `.ghfs/pulls/**/*.md`)
+3. `execute.yml` (explicit YAML operations)
 
-## Execute operations
+Note: execution merge order is `execute.yml` -> `execute.md` -> `per-issue` generated operations.
 
-`ghfs` also allows you to take actions on the issues and pull requests in batch.
+### 1) `execute.md` (recommended)
+
+`execute.md` is best for quick/manual batching:
+
+```md
+close #123 #234
+set-title #125 "New title"
+label #125 bug, enhancement
+close-comment #126 "Closing this as completed"
+```
+
+Action names in both `execute.yml` and `execute.md` are case-insensitive and support aliases, including:
+
+- `closes` -> `close`
+- `open` -> `reopen`
+- `close-comment` / `comment-close` / `close-and-comment` / `comment-and-close` -> `close-with-comment`
+
+`execute.md` also supports comment lines with `#` and `//`, plus HTML comment blocks using `<!-- ... -->`. These comments are preserved when operations are rewritten.
+
+### 2) Per-issue operations
+
+Edit frontmatter directly in issue/PR markdown files:
+
+- `title`
+- `state` (`open` / `closed`)
+- `labels`
+- `assignees`
+- `milestone`
+
+`ghfs execute` will diff these values and generate operations automatically (for example `set-title`, `close`/`reopen`, label updates, assignee updates, milestone updates).
+
+### 3) `execute.yml`
 
 `ghfs sync` or `ghfs execute` will auto-create `.ghfs/execute.yml` and `.ghfs/schema/execute.schema.json` if missing.
-Then edit `.ghfs/execute.yml` with content like:
+Use `execute.yml` for explicit/low-level operations:
 
 ```yaml
 # close the issue #123
@@ -68,20 +100,13 @@ Then edit `.ghfs/execute.yml` with content like:
   labels: [bug, feature]
 ```
 
-Then run
+Then run `ghfs execute` to preview, and `ghfs execute --run` to execute.
 
 ```bash
 ghfs execute
+ghfs execute --run
 ```
 
-to execute the operations in batch.
-
-When running `ghfs execute --apply`:
-- Each successfully applied operation is removed from `.ghfs/execute.yml`.
-- After execution, `ghfs` runs a targeted sync only for affected issue/PR numbers.
-
-> TODO: directly editing the `<5-digit-number>-<slug>.md` file to apply the operations will be rolled out in the future.
-
 ## Agent Skill
 
 This repository ships an [agent skill](https://agentskills.io/home) at [`skills/ghfs/SKILL.md`](skills/ghfs/SKILL.md).
@@ -118,9 +143,10 @@ export default defineConfig({
 
 ## TODOs
 
-- [ ] `execute.md` file with human-friendly instructions (`close #123 #234`, `set-title #125 "New title"`).
+- [x] `execute.md` file with human-friendly instructions (`close #123 #234`, `set-title #125 "New title"`).
 - [x] Directly editing the `<5-digit-number>-<slug>.md` file to apply the operations.
 - [ ] Add a VS Code extension for guided sync/execute.
 - [ ] Documentation.
 - [x] Index page, and basic repo info
 - [x] Agent Skills.
+- [ ] Local Web UI for managing the local mirror.

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };