@ghfs/cli 0.0.0 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +101 -72
  3. package/dist/cli.mjs +1928 -927
  4. package/dist/factory-CNz1r4PQ.mjs +428 -0
  5. package/dist/index.d.mts +180 -39
  6. package/dist/index.mjs +3 -1
  7. package/package.json +39 -13
  8. package/skills/ghfs/SKILL.md +98 -0
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,97 +1,126 @@
1
1
  # ghfs
2
2
 
3
- Mirror GitHub issues and pull requests to local markdown files, then execute maintainer actions in batch from `.ghfs/execute.yml`.
3
+ GitHub issues/PRs as filesystem, for offline view and operations in batch. Designed for human and agents.
4
4
 
5
- ## Install
5
+ > [!IMPORTANT]
6
+ > Still working in progress, not usable yet.
6
7
 
7
8
  ```bash
8
- pnpm install
9
- pnpm build
9
+ pnpm install @ghfs/cli
10
10
  ```
11
11
 
12
- ## Commands
12
+ and then run the command inside a repository directory:
13
13
 
14
14
  ```bash
15
- ghfs # same as `ghfs sync`
16
- ghfs sync [--repo owner/name] [--since ISO] [--full]
17
- ghfs execute [--file .ghfs/execute.yml] [--apply] [--non-interactive] [--continue-on-error]
18
- ghfs status
19
- ghfs schema
15
+ ghfs
20
16
  ```
21
17
 
22
- ## Config (`ghfs.config.ts`)
23
-
24
- ```ts
25
- import { defineConfig } from '@ghfs/cli'
26
-
27
- export default defineConfig({
28
- repo: 'owner/name',
29
- storageDir: '.ghfs',
30
- executeFile: '.ghfs/execute.yml',
31
- })
32
- ```
33
-
34
- Precedence: `CLI flags > ghfs.config.ts > auto-detect (.git/package.json) > .ghfs/.sync.json`.
35
-
36
- ## Local Files
18
+ It will sync the open issues and pull requests to the local filesystem under `.ghfs` directory, like:
37
19
 
38
20
  ```txt
39
21
  .ghfs/
40
- .sync.json
41
- execute.yml
42
- schema/execute.schema.json
22
+ repo.json # repository basic information
23
+ issues.md # index of fetched issues
24
+ pulls.md # index of fetched pull requests
43
25
  issues/
44
- 123.md
45
- 123.patch
26
+ 00134-some-bug.md
46
27
  closed/
47
- 124.md
28
+ 00135-fixed-crash.md
29
+ pulls/
30
+ 00042-add-cache.md
31
+ 00042-add-cache.patch
32
+ closed/
33
+ 00043-release-cleanup.md
48
34
  ```
49
35
 
50
- - Open issues/PRs: `.ghfs/issues/<number>.md`
51
- - Closed issues/PRs: `.ghfs/issues/closed/<number>.md`
52
- - Open PR patch: `.ghfs/issues/<number>.patch`
53
-
54
- ## Execute Actions
55
-
56
- Supported `action` values:
57
-
58
- - `close`
59
- - `reopen`
60
- - `set-title`
61
- - `set-body`
62
- - `add-comment`
63
- - `add-labels`
64
- - `remove-labels`
65
- - `set-labels`
66
- - `add-assignees`
67
- - `remove-assignees`
68
- - `set-assignees`
69
- - `set-milestone`
70
- - `clear-milestone`
71
- - `lock`
72
- - `unlock`
73
- - `request-reviewers` (PR)
74
- - `remove-reviewers` (PR)
75
- - `mark-ready-for-review` (PR)
76
- - `convert-to-draft` (PR)
77
-
78
- Each entry is one action object with `action`, `number`, and action-specific payload fields.
79
-
80
- ## Execute File Example
36
+ Then you can view them offline, or ask your local agent to summarize them for you.
37
+
38
+ ## CLI feedback
39
+
40
+ `ghfs` now provides stage-based sync feedback.
41
+
42
+ - In interactive terminals (TTY), `ghfs` uses rich progress indicators.
43
+ - In CI or piped output, `ghfs` prints deterministic plain-text progress lines.
44
+ - `ghfs sync --full` bypasses metadata early-return and runs full pagination.
45
+
46
+ `ghfs status` now also includes diagnostics from the latest sync run (duration, request count, counters, and stage timings) from `.ghfs/.sync.json`.
47
+
48
+ ## Execute operations
49
+
50
+ `ghfs` also allows you to take actions on the issues and pull requests in batch.
51
+
52
+ `ghfs sync` or `ghfs execute` will auto-create `.ghfs/execute.yml` and `.ghfs/schema/execute.schema.json` if missing.
53
+ Then edit `.ghfs/execute.yml` with content like:
81
54
 
82
55
  ```yaml
56
+ # close the issue #123
57
+ - action: close
58
+ number: 123
59
+
60
+ # change the title of the issue #125 to "New title"
61
+ - action: set-title
62
+ number: 125
63
+ title: New title
64
+
65
+ # add the labels "bug" and "feature" to the issue #125
83
66
  - action: add-labels
84
- number: 12
85
- labels: [triage]
86
- - action: request-reviewers
87
- number: 45
88
- reviewers: [alice, bob]
67
+ number: 125
68
+ labels: [bug, feature]
69
+ ```
70
+
71
+ Then run
72
+
73
+ ```bash
74
+ ghfs execute
75
+ ```
76
+
77
+ to execute the operations in batch.
78
+
79
+ When running `ghfs execute --apply`:
80
+ - Each successfully applied operation is removed from `.ghfs/execute.yml`.
81
+ - After execution, `ghfs` runs a targeted sync only for affected issue/PR numbers.
82
+
83
+ > TODO: directly editing the `<5-digit-number>-<slug>.md` file to apply the operations will be rolled out in the future.
84
+
85
+ ## Agent Skill
86
+
87
+ This repository ships an [agent skill](https://agentskills.io/home) at [`skills/ghfs/SKILL.md`](skills/ghfs/SKILL.md).
88
+
89
+ Install with [`skills`](https://github.com/vercel-labs/skills) CLI:
90
+
91
+ ```bash
92
+ pnpx skills add antfu/ghfs
93
+ ```
94
+
95
+ The `@ghfs/cli` also ship the skills into the npm package that you can have it also installed with [`skills-npm`](https://github.com/antfu/skills-npm):
96
+
97
+ ```bash
98
+ pnpm i -D @ghfs/cli
99
+ pnpx skills-npm
89
100
  ```
90
101
 
91
- ## Authentication
102
+ ## Configuration
103
+
104
+ You can configure by creating a `ghfs.config.ts` file in the root of the repository.
105
+
106
+ ```ts
107
+ import type { GhfsUserConfig } from '@ghfs/cli'
108
+
109
+ export default defineConfig({
110
+ repo: 'owner/name',
111
+ sync: {
112
+ issues: true, // set false to skip issue sync
113
+ pulls: true, // set false to skip pull request sync
114
+ },
115
+ // other options...
116
+ })
117
+ ```
92
118
 
93
- 1. `gh auth token` (preferred)
94
- 2. `GH_TOKEN` / `GITHUB_TOKEN`
95
- 3. TTY prompt on first run
119
+ ## TODOs
96
120
 
97
- In non-TTY mode, missing auth token is a hard error.
121
+ - [ ] `execute.md` file with human-friendly instructions (`close #123 #234`, `set-title #125 "New title"`).
122
+ - [x] Directly editing the `<5-digit-number>-<slug>.md` file to apply the operations.
123
+ - [ ] Add a VS Code extension for guided sync/execute.
124
+ - [ ] Documentation.
125
+ - [x] Index page, and basic repo info
126
+ - [x] Agent Skills.