@astrazds/fjgo 1.4.1 → 1.4.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.
- package/README.md +101 -121
- package/package.json +19 -3
package/README.md
CHANGED
|
@@ -1,179 +1,159 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://repos.astrazds.net/astrazds/fjgo/raw/branch/main/docs/assets/readme/fjgo-icon.png" width="112" height="112" alt="fjgo icon">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">fjgo</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
Agent-first Forgejo CLI for coding agents.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://repos.astrazds.net/astrazds/fjgo/src/branch/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/@astrazds/fjgo"><img alt="npm" src="https://img.shields.io/npm/v/@astrazds/fjgo.svg"></a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
`fjgo` gives coding agents a safe, compact way to work with [Forgejo](https://forgejo.org/) repositories. It covers issues, pull requests, Actions, releases, labels, secrets, and the rest of the bundled Forgejo API, with TOON stdout, structured errors, and token-safe dry runs.
|
|
17
|
+
|
|
18
|
+
Use normal `git` for commits, branches, and local files. Use `fjgo` for work that needs the Forgejo server.
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
$ npx -y @astrazds/fjgo -R origin issue list --state open
|
|
22
|
+
count: 3 of 3 total
|
|
23
|
+
issues[3]{number,title,state}:
|
|
24
|
+
12,Redact API diagnostics,open
|
|
25
|
+
9,Separate watch timeout,closed
|
|
26
|
+
4,Publish wiki manual,closed
|
|
27
|
+
help[1]{command}:
|
|
28
|
+
Run `fjgo issue view 12` to see full details
|
|
29
|
+
```
|
|
9
30
|
|
|
10
|
-
## Why
|
|
31
|
+
## Why fjgo?
|
|
11
32
|
|
|
12
|
-
An agent can call the Forgejo API with `curl`, but it has to remember URLs,
|
|
13
|
-
JSON shapes, and authentication rules. That creates extra work and makes
|
|
14
|
-
mistakes more likely.
|
|
33
|
+
An agent can call the Forgejo API with `curl`, but it has to remember URLs, JSON shapes, and authentication rules. That creates extra work and makes mistakes more likely.
|
|
15
34
|
|
|
16
|
-
`fjgo`
|
|
35
|
+
`fjgo` keeps the expensive parts in one tool:
|
|
17
36
|
|
|
18
37
|
- short commands for common Forgejo jobs;
|
|
19
|
-
- compact output that uses fewer tokens;
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
|
|
25
|
-
Use normal `git` commands for commits, branches, and local files. Use `fjgo`
|
|
26
|
-
for tasks that need the Forgejo server.
|
|
38
|
+
- compact TOON output that uses fewer tokens;
|
|
39
|
+
- structured errors and focused `--help`;
|
|
40
|
+
- `--dry-run` / `--print-request` before writes;
|
|
41
|
+
- token, password, and OTP values kept out of stdout;
|
|
42
|
+
- generated coverage of every operation in the pinned Forgejo Swagger.
|
|
27
43
|
|
|
28
44
|
## Install
|
|
29
45
|
|
|
30
|
-
|
|
46
|
+
The public npm package is `@astrazds/fjgo` because unscoped `fjgo` is blocked on the npm registry. The command name remains `fjgo`. Node.js 20 or newer is required, on Linux or macOS with an x64 or arm64 CPU.
|
|
31
47
|
|
|
32
|
-
|
|
48
|
+
### Agent Skill
|
|
33
49
|
|
|
34
50
|
```sh
|
|
35
51
|
npx skills add https://repos.astrazds.net/astrazds/fjgo.git --skill fjgo -g
|
|
36
52
|
```
|
|
37
53
|
|
|
38
|
-
That is the full setup. You do not need to clone this repository or run
|
|
39
|
-
`npm install`.
|
|
54
|
+
That is the full setup. You do not need to clone this repository or run `npm install`. The skill runs the CLI through `npx -y @astrazds/fjgo`. The first run downloads the matching native release, verifies its checksum, and caches it.
|
|
40
55
|
|
|
41
|
-
|
|
42
|
-
The npm package is scoped because unscoped `fjgo` is blocked on the public
|
|
43
|
-
registry. The installed command name remains `fjgo`. The first run downloads
|
|
44
|
-
the matching native release and saves it in a local cache. Later runs reuse
|
|
45
|
-
that copy.
|
|
46
|
-
|
|
47
|
-
Requirements: Node.js 20 or newer, on Linux or macOS with an x64 or arm64 CPU.
|
|
48
|
-
|
|
49
|
-
Without Node.js, install a native release archive:
|
|
56
|
+
### Native archive
|
|
50
57
|
|
|
51
58
|
```sh
|
|
52
|
-
curl -LO https://repos.astrazds.net/astrazds/fjgo/releases/download/v1.4.
|
|
53
|
-
tar -xzf fjgo_v1.4.
|
|
54
|
-
install -Dm755 fjgo_v1.4.
|
|
59
|
+
curl -LO https://repos.astrazds.net/astrazds/fjgo/releases/download/v1.4.2/fjgo_v1.4.2_linux_amd64.tar.gz
|
|
60
|
+
tar -xzf fjgo_v1.4.2_linux_amd64.tar.gz
|
|
61
|
+
install -Dm755 fjgo_v1.4.2_linux_amd64/fjgo ~/.local/bin/fjgo
|
|
55
62
|
```
|
|
56
63
|
|
|
57
|
-
Use `darwin` instead of `linux`, and `arm64` instead of `amd64`, when that
|
|
58
|
-
matches the machine. Then run `fjgo` directly instead of `npx -y @astrazds/fjgo`.
|
|
64
|
+
Use `darwin` instead of `linux`, and `arm64` instead of `amd64`, when that matches the machine. Then run `fjgo` directly.
|
|
59
65
|
|
|
60
66
|
### Optional ambient hooks
|
|
61
67
|
|
|
62
|
-
The skill and the native binary are enough for on-demand use. If you want
|
|
63
|
-
Forgejo context injected at the start of every agent session, install the
|
|
64
|
-
optional hooks after the CLI is on PATH:
|
|
68
|
+
The skill and the native binary are enough for on-demand use. If you want Forgejo context at the start of every agent session:
|
|
65
69
|
|
|
66
70
|
```sh
|
|
67
71
|
npx -y @astrazds/fjgo setup hooks --check
|
|
68
72
|
npx -y @astrazds/fjgo setup hooks
|
|
69
73
|
```
|
|
70
74
|
|
|
71
|
-
You only need the skill or the hooks. Installing both is fine
|
|
72
|
-
live session context, and the skill remains available on demand.
|
|
75
|
+
You only need the skill or the hooks. Installing both is fine.
|
|
73
76
|
|
|
74
77
|
### Codex plugin
|
|
75
78
|
|
|
76
|
-
This repository is also a validated Codex plugin package. A marketplace can
|
|
77
|
-
point at the repository root to distribute the existing `fjgo` skill with
|
|
78
|
-
plugin presentation metadata and starter prompts. Until a marketplace lists
|
|
79
|
-
it, the Agent Skill command above remains the shortest public installation
|
|
80
|
-
path.
|
|
81
|
-
|
|
82
|
-
The plugin still runs `npx -y @astrazds/fjgo`; it does not bundle another API client,
|
|
83
|
-
install ambient hooks automatically, provide OAuth, or store credentials.
|
|
84
|
-
See [Codex plugin](docs/codex-plugin.md) for marketplace installation, local
|
|
85
|
-
testing, authentication, and maintenance details.
|
|
79
|
+
This repository is also a validated Codex plugin package. A marketplace can point at the repository root to distribute the existing skill with branding and starter prompts. Until a marketplace lists it, the Agent Skill command above remains the shortest public path. See [Codex plugin](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/docs/codex-plugin.md).
|
|
86
80
|
|
|
87
|
-
##
|
|
81
|
+
## Use
|
|
88
82
|
|
|
89
|
-
Set
|
|
83
|
+
Set the Forgejo host. Add a token for private repos or writes. Do not paste the token into an agent prompt.
|
|
90
84
|
|
|
91
85
|
```sh
|
|
92
86
|
export FJGO_HOST=forgejo.example.com
|
|
93
87
|
export FJGO_TOKEN=your_access_token
|
|
94
88
|
```
|
|
95
89
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
90
|
+
1. Orient inside a checkout whose Forgejo remote is `origin`: `npx -y @astrazds/fjgo -R origin`
|
|
91
|
+
2. Inspect work with `doctor`, `issue list`, `pr list`, and `run list`.
|
|
92
|
+
3. Preview a write with `--dry-run --yes`. Apply it by dropping `--dry-run`.
|
|
93
|
+
|
|
94
|
+
```mermaid
|
|
95
|
+
flowchart LR
|
|
96
|
+
A[Agent] --> S[Skill or session hook]
|
|
97
|
+
S --> H["fjgo / doctor"]
|
|
98
|
+
H --> C["issue / pr / run"]
|
|
99
|
+
C --> D["dry-run --yes"]
|
|
100
|
+
D --> M["mutation --yes"]
|
|
101
|
+
H --> G["api inspect / call / raw"]
|
|
102
|
+
```
|
|
101
103
|
|
|
102
|
-
|
|
103
|
-
`origin`:
|
|
104
|
+
`-R origin` reads `OWNER/REPO` from the Git remote. You can also pass `--repo OWNER/REPO` or `FJGO_REPO`. Every command has focused `--help`.
|
|
104
105
|
|
|
105
106
|
```sh
|
|
106
|
-
npx -y @astrazds/fjgo -R origin
|
|
107
|
-
npx -y @astrazds/fjgo -R origin doctor
|
|
108
107
|
npx -y @astrazds/fjgo -R origin issue list --state open
|
|
109
|
-
npx -y @astrazds/fjgo -R origin pr
|
|
110
|
-
npx -y @astrazds/fjgo
|
|
108
|
+
npx -y @astrazds/fjgo -R origin pr checks 12
|
|
109
|
+
npx -y @astrazds/fjgo issue create --title "Fix the login page" --dry-run --yes
|
|
111
110
|
```
|
|
112
111
|
|
|
113
|
-
|
|
114
|
-
also choose a repository directly:
|
|
112
|
+
## Privacy
|
|
115
113
|
|
|
116
|
-
|
|
117
|
-
npx -y @astrazds/fjgo --repo OWNER/REPO repo get
|
|
118
|
-
npx -y @astrazds/fjgo issue list OWNER/REPO --state open
|
|
119
|
-
```
|
|
114
|
+
`fjgo` has no backend, analytics, advertising, or telemetry. It does not store Forgejo credentials. Host and token come from the environment or flags on this machine.
|
|
120
115
|
|
|
121
|
-
|
|
116
|
+
| Location | Purpose |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `FJGO_TOKEN` / `--token` | User-supplied access token; never written by fjgo |
|
|
119
|
+
| `doctor` / `auth status` | Show whether credentials are present, not their values |
|
|
120
|
+
| `--dry-run` / `--print-request` | Token-safe request previews |
|
|
121
|
+
| npm launcher cache | Checksum-verified native binary only |
|
|
122
122
|
|
|
123
|
-
|
|
124
|
-
`--dry-run` first:
|
|
123
|
+
See [PRIVACY.md](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/PRIVACY.md) for the complete data boundary.
|
|
125
124
|
|
|
126
|
-
|
|
127
|
-
npx -y @astrazds/fjgo -R origin issue create \
|
|
128
|
-
--title "Fix the login page" \
|
|
129
|
-
--body "The login button is not working." \
|
|
130
|
-
--dry-run --yes
|
|
131
|
-
```
|
|
125
|
+
## Limitations
|
|
132
126
|
|
|
133
|
-
|
|
127
|
+
- Linux and macOS on x64 or arm64. The npm launcher does not support Windows.
|
|
128
|
+
- Forgejo only. It is not a GitHub or GitLab client.
|
|
129
|
+
- Mutating commands require `--yes`. There are no interactive prompts.
|
|
130
|
+
- Codex marketplace publication is separate from fjgo releases.
|
|
131
|
+
- Ambient `FJGO_TOKEN` is ignored on the public demo API unless the host or base URL is set explicitly.
|
|
134
132
|
|
|
135
|
-
|
|
136
|
-
npx -y @astrazds/fjgo -R origin issue create \
|
|
137
|
-
--title "Fix the login page" \
|
|
138
|
-
--body "The login button is not working." \
|
|
139
|
-
--yes
|
|
140
|
-
```
|
|
133
|
+
## Project structure
|
|
141
134
|
|
|
142
|
-
|
|
135
|
+
| Path | Purpose |
|
|
136
|
+
| --- | --- |
|
|
137
|
+
| `cmd/fjgo/` | CLI parsing, AXI output, curated commands, hooks |
|
|
138
|
+
| `internal/forgejo/` | HTTP client and generated Swagger methods/models |
|
|
139
|
+
| `internal/fjgoskill/` | Embedded skill and installer |
|
|
140
|
+
| `internal/benchmark/` | Offline agent-job catalog and baseline |
|
|
141
|
+
| `skills/fjgo/` | Public Agent Skill invoked through `npx -y @astrazds/fjgo` |
|
|
142
|
+
| `docs/` | CLI reference, plugin, development, and wiki sources |
|
|
143
|
+
| `scripts/verify.sh` | Local and CI verification gate |
|
|
143
144
|
|
|
144
|
-
|
|
145
|
-
npx -y @astrazds/fjgo -R origin issue view 42 --comments --full
|
|
146
|
-
npx -y @astrazds/fjgo -R origin pr checks 12
|
|
147
|
-
npx -y @astrazds/fjgo -R origin release list
|
|
148
|
-
npx -y @astrazds/fjgo -R origin workflow list
|
|
149
|
-
npx -y @astrazds/fjgo -R origin search issues "login" --state open
|
|
150
|
-
```
|
|
145
|
+
The [wiki manual](https://repos.astrazds.net/astrazds/fjgo/wiki) is the short operator guide. [CLI reference](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/docs/cli-reference.md) covers authentication, output, command groups, and the generic API escape hatch.
|
|
151
146
|
|
|
152
|
-
|
|
147
|
+
## Development
|
|
148
|
+
|
|
149
|
+
Go 1.26 and Node.js 20 or newer are required.
|
|
153
150
|
|
|
154
151
|
```sh
|
|
155
|
-
|
|
156
|
-
|
|
152
|
+
npm ci
|
|
153
|
+
./scripts/verify.sh
|
|
154
|
+
go run ./cmd/fjgo-benchmark
|
|
157
155
|
```
|
|
158
156
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
guidance published through Forgejo from the reviewed sources in `docs/wiki`.
|
|
163
|
-
- [CLI reference](docs/cli-reference.md): authentication, repository selection,
|
|
164
|
-
output, command groups, and the full API escape hatch.
|
|
165
|
-
- [Agent setup prompt](docs/agent-setup-prompt.md): a ready-to-paste setup prompt
|
|
166
|
-
for another coding agent.
|
|
167
|
-
- [Codex plugin](docs/codex-plugin.md): plugin packaging, marketplace
|
|
168
|
-
installation, authentication boundaries, and validation.
|
|
169
|
-
- [Development guide](docs/development.md): build, test, generate code, and make
|
|
170
|
-
releases, including the deterministic offline agent-job benchmark and its
|
|
171
|
-
scenario-run record format. CI runs through `.forgejo/workflows/verify.yml`.
|
|
172
|
-
- [AXI compliance](docs/axi-compliance.md): the agent-friendly interface rules
|
|
173
|
-
followed by `fjgo`.
|
|
174
|
-
- [Field validation](docs/alpha.md): the v1.4.1 live-testing checklist.
|
|
175
|
-
- [Changelog](CHANGELOG.md): release history.
|
|
176
|
-
|
|
177
|
-
## License
|
|
178
|
-
|
|
179
|
-
MIT
|
|
157
|
+
CI on `main` is `.forgejo/workflows/verify.yml`. Open the [Actions log](https://repos.astrazds.net/astrazds/fjgo/actions?workflow=verify.yml) for recent runs. Tag `v*` releases build archives, publish the Forgejo release from `CHANGELOG.md`, and publish `@astrazds/fjgo`. See [Development](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/docs/development.md).
|
|
158
|
+
|
|
159
|
+
Contributions are welcome; read [CONTRIBUTING.md](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/CONTRIBUTING.md) before opening a pull request. Security reports use [SECURITY.md](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/SECURITY.md). fjgo is licensed under [MIT](https://repos.astrazds.net/astrazds/fjgo/src/branch/main/LICENSE).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astrazds/fjgo",
|
|
3
|
-
"version": "1.4.
|
|
4
|
-
"description": "Agent-first CLI
|
|
3
|
+
"version": "1.4.2",
|
|
4
|
+
"description": "Agent-first Forgejo CLI for coding agents.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -15,11 +15,27 @@
|
|
|
15
15
|
"engines": {
|
|
16
16
|
"node": ">=20"
|
|
17
17
|
},
|
|
18
|
+
"author": {
|
|
19
|
+
"name": "Andrejs Strazds",
|
|
20
|
+
"url": "https://repos.astrazds.net/astrazds"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [
|
|
23
|
+
"agents",
|
|
24
|
+
"api-client",
|
|
25
|
+
"axi",
|
|
26
|
+
"cli",
|
|
27
|
+
"codex",
|
|
28
|
+
"forgejo",
|
|
29
|
+
"go",
|
|
30
|
+
"openapi",
|
|
31
|
+
"swagger",
|
|
32
|
+
"toon"
|
|
33
|
+
],
|
|
18
34
|
"repository": {
|
|
19
35
|
"type": "git",
|
|
20
36
|
"url": "git+https://repos.astrazds.net/astrazds/fjgo.git"
|
|
21
37
|
},
|
|
22
|
-
"homepage": "https://repos.astrazds.net/astrazds/fjgo",
|
|
38
|
+
"homepage": "https://repos.astrazds.net/astrazds/fjgo/wiki",
|
|
23
39
|
"bugs": {
|
|
24
40
|
"url": "https://repos.astrazds.net/astrazds/fjgo/issues"
|
|
25
41
|
},
|