@ghfs/cli 0.0.0 → 0.0.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,97 +1,126 @@
 # ghfs
 
-Mirror GitHub issues and pull requests to local markdown files, then execute maintainer actions in batch from `.ghfs/execute.yml`.
+GitHub issues/PRs as filesystem, for offline view and operations in batch. Designed for human and agents.
 
-## Install
+> [!IMPORTANT]
+> Still working in progress, not usable yet.
 
 ```bash
-pnpm install
-pnpm build
+pnpm install @ghfs/cli
 ```
 
-## Commands
+and then run the command inside a repository directory:
 
 ```bash
-ghfs                      # same as `ghfs sync`
-ghfs sync [--repo owner/name] [--since ISO] [--full]
-ghfs execute [--file .ghfs/execute.yml] [--apply] [--non-interactive] [--continue-on-error]
-ghfs status
-ghfs schema
+ghfs
 ```
 
-## Config (`ghfs.config.ts`)
-
-```ts
-import { defineConfig } from '@ghfs/cli'
-
-export default defineConfig({
-  repo: 'owner/name',
-  storageDir: '.ghfs',
-  executeFile: '.ghfs/execute.yml',
-})
-```
-
-Precedence: `CLI flags > ghfs.config.ts > auto-detect (.git/package.json) > .ghfs/.sync.json`.
-
-## Local Files
+It will sync the open issues and pull requests to the local filesystem under `.ghfs` directory, like:
 
 ```txt
 .ghfs/
-  .sync.json
-  execute.yml
-  schema/execute.schema.json
+  repo.json  # repository basic information
+  issues.md  # index of fetched issues
+  pulls.md   # index of fetched pull requests
   issues/
-    123.md
-    123.patch
+    00134-some-bug.md
     closed/
-      124.md
+      00135-fixed-crash.md
+  pulls/
+    00042-add-cache.md
+    00042-add-cache.patch
+    closed/
+      00043-release-cleanup.md
 ```
 
-- Open issues/PRs: `.ghfs/issues/<number>.md`
-- Closed issues/PRs: `.ghfs/issues/closed/<number>.md`
-- Open PR patch: `.ghfs/issues/<number>.patch`
-
-## Execute Actions
-
-Supported `action` values:
-
-- `close`
-- `reopen`
-- `set-title`
-- `set-body`
-- `add-comment`
-- `add-labels`
-- `remove-labels`
-- `set-labels`
-- `add-assignees`
-- `remove-assignees`
-- `set-assignees`
-- `set-milestone`
-- `clear-milestone`
-- `lock`
-- `unlock`
-- `request-reviewers` (PR)
-- `remove-reviewers` (PR)
-- `mark-ready-for-review` (PR)
-- `convert-to-draft` (PR)
-
-Each entry is one action object with `action`, `number`, and action-specific payload fields.
-
-## Execute File Example
+Then you can view them offline, or ask your local agent to summarize them for you.
+
+## CLI feedback
+
+`ghfs` now provides stage-based sync feedback.
+
+- 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 status` now also includes diagnostics from the latest sync run (duration, request count, counters, and stage timings) from `.ghfs/.sync.json`.
+
+## Execute operations
+
+`ghfs` also allows you to take actions on the issues and pull requests in batch.
+
+`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:
 
 ```yaml
+# close the issue #123
+- action: close
+  number: 123
+
+# change the title of the issue #125 to "New title"
+- action: set-title
+  number: 125
+  title: New title
+
+# add the labels "bug" and "feature" to the issue #125
 - action: add-labels
-  number: 12
-  labels: [triage]
-- action: request-reviewers
-  number: 45
-  reviewers: [alice, bob]
+  number: 125
+  labels: [bug, feature]
+```
+
+Then run
+
+```bash
+ghfs execute
+```
+
+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).
+
+Install with [`skills`](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+pnpx skills add antfu/ghfs
+```
+
+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):
+
+```bash
+pnpm i -D @ghfs/cli
+pnpx skills-npm
 ```
 
-## Authentication
+## Configuration
+
+You can configure by creating a `ghfs.config.ts` file in the root of the repository.
+
+```ts
+import type { GhfsUserConfig } from '@ghfs/cli'
+
+export default defineConfig({
+  repo: 'owner/name',
+  sync: {
+    issues: true, // set false to skip issue sync
+    pulls: true, // set false to skip pull request sync
+  },
+  // other options...
+})
+```
 
-1. `gh auth token` (preferred)
-2. `GH_TOKEN` / `GITHUB_TOKEN`
-3. TTY prompt on first run
+## TODOs
 
-In non-TTY mode, missing auth token is a hard error.
+- [ ] `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.

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@ghfs/cli",
   "type": "module",
-  "version": "0.0.0",
-  "packageManager": "pnpm@10.30.3",
-  "description": "Mirror GitHub issues and PRs to local markdown files and execute batch maintainer actions.",
+  "version": "0.0.1",
+  "description": "GitHub issues/PRs as filesystem, for offline view and operations in batch. Designed for human and agents.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/antfu",
+  "homepage": "https://github.com/antfu/ghfs",
+  "repository": "https://github.com/antfu/ghfs",
+  "bugs": "https://github.com/antfu/ghfs/issues",
+  "keywords": [
+    "github",
+    "issues",
+    "pull requests",
+    "markdown",
+    "cli"
+  ],
   "exports": {
     ".": "./dist/index.mjs",
     "./cli": "./dist/cli.mjs",
@@ -14,33 +26,47 @@
     "ghfs": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills/ghfs"
   ],
-  "scripts": {
-    "build": "tsdown",
-    "start": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "lint": "eslint",
-    "schema": "tsx src/cli.ts schema"
-  },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
     "@octokit/plugin-retry": "^8.1.0",
     "@octokit/plugin-throttling": "^11.0.3",
+    "ansis": "^4.2.0",
     "cac": "^7.0.0",
+    "dotenv": "^17.3.1",
     "jiti": "^2.6.1",
     "octokit": "^5.0.5",
+    "pathe": "^2.0.3",
     "valibot": "^1.1.0",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.6.1",
     "@types/node": "^25.3.3",
+    "bumpp": "^10.4.1",
     "eslint": "^10.0.2",
+    "lint-staged": "^16.3.2",
+    "simple-git-hooks": "^2.13.1",
     "tsdown": "^0.20.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint",
+    "release": "bumpp",
+    "play": "cd playgrounds/ni && tsx ../../src/cli.ts"
   }
-}
+}

package/skills/ghfs/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ghfs
+description: Manages ghfs local mirror files in `.ghfs/`, especially translating user instructions into valid `.ghfs/execute.yml` operations, running `ghfs execute` / `ghfs sync`, and validating issue/PR batch edits. Use when tasks involve editing issues/PRs through `.ghfs` artifacts, reconciling sync state, or applying queued GitHub operations.
+---
+
+# Ghfs
+
+## Overview
+
+Use this skill to operate ghfs as a local filesystem mirror for GitHub issues and pull requests.
+
+- `ghfs sync` mirrors remote content into `.ghfs/`.
+- `ghfs execute` reads `.ghfs/execute.yml` and plans or applies mutations.
+- Default execute mode is dry-run. Use `--apply` to mutate GitHub.
+
+Key `.ghfs` files:
+- `execute.yml`: queued operations (YAML array)
+- `schema/execute.schema.json`: schema for `execute.yml`
+- `.sync.json`: sync and execution run history (skip reading it)
+- `issues.md`, `pulls.md`, `repo.json`: aggregated mirror views
+- `issues/**/*.md`, `pulls/**/*.md`: per-item mirrors
+
+## Main Workflow
+
+1. Sync first when local data may be stale: run `ghfs sync`.
+2. Update `.ghfs/execute.yml` from user instructions.
+3. Validate and preview with `ghfs execute`.
+4. Apply only on explicit user intent: `ghfs execute --apply`.
+5. Report results and remaining queued operations.
+
+Execution behavior to remember:
+- Operations run in file order.
+- On `--apply`, each successful operation is removed from `execute.yml`.
+- Failed and not-yet-run operations stay in `execute.yml`.
+- After apply, ghfs runs targeted sync for affected numbers automatically.
+
+## Update `.ghfs/execute.yml` Correctly
+
+Keep root as a YAML array and include `number` + `action` for every entry.
+
+```yaml
+# yaml-language-server: $schema=./schema/execute.schema.json
+- number: 125
+  action: set-title
+  title: Improve sync summary output
+
+- number: 125
+  action: add-labels
+  labels: [enhancement, cli]
+
+- number: 126
+  action: request-reviewers
+  reviewers: [octocat]
+  ifUnchangedSince: '2026-03-05T04:10:00Z'
+```
+
+Map user intent to action fields:
+
+| User intent | action | Required extra fields |
+| --- | --- | --- |
+| Close / reopen | `close`, `reopen` | none |
+| Change title | `set-title` | `title` |
+| Replace body | `set-body` | `body` |
+| Add comment | `add-comment` | `body` |
+| Add/remove/set labels | `add-labels`, `remove-labels`, `set-labels` | `labels` (non-empty string array) |
+| Add/remove/set assignees | `add-assignees`, `remove-assignees`, `set-assignees` | `assignees` (non-empty string array) |
+| Set/clear milestone | `set-milestone`, `clear-milestone` | `milestone` for set |
+| Lock/unlock conversation | `lock`, `unlock` | optional `reason` for lock |
+| PR reviewer actions | `request-reviewers`, `remove-reviewers` | `reviewers` (non-empty string array) |
+| PR draft state | `mark-ready-for-review`, `convert-to-draft` | none |
+
+Rules:
+- `number` must be a positive integer.
+- `ifUnchangedSince` must be ISO datetime when present.
+- `request-reviewers`, `remove-reviewers`, `mark-ready-for-review`, and `convert-to-draft` are PR-only.
+- Keep operation order aligned with user intent because execution is sequential.
+- Append operations unless user explicitly asks to replace or clear the queue.
+
+Practical number resolution:
+- Parse from filenames such as `.ghfs/issues/00123-foo.md` -> `number: 123`.
+- Use `.ghfs/issues.md` / `.ghfs/pulls.md` when matching by title.
+
+## Run Sync and Execute via CLI
+
+Preferred commands:
+
+```bash
+ghfs sync
+ghfs sync --full
+ghfs sync --since 2026-03-01T00:00:00Z
+ghfs execute
+ghfs execute --apply
+```
+
+Useful flags:
+- `--repo owner/name` when repo cannot be auto-resolved.
+- `--non-interactive` for scripted runs.
+- `--continue-on-error` to keep applying later ops after a failure.

package/dist/cli.d.mts

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