@astrazds/fjgo 1.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrejs Strazds
+
+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

@@ -0,0 +1,179 @@
+# fjgo
+
+`fjgo` helps coding agents work with repositories hosted on
+[Forgejo](https://forgejo.org/).
+
+It can read and update issues, pull requests, releases, Actions runs,
+repository settings, labels, secrets, and more. It also gives agents a safe
+way to use the full Forgejo API when there is no shorter command.
+
+## Why use it?
+
+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.
+
+`fjgo` gives the agent:
+
+- short commands for common Forgejo jobs;
+- compact output that uses fewer tokens;
+- clear errors and help;
+- safe request previews before making changes;
+- automatic protection against printing passwords or API tokens;
+- access to every operation in the bundled Forgejo API specification.
+
+Use normal `git` commands for commits, branches, and local files. Use `fjgo`
+for tasks that need the Forgejo server.
+
+## Install
+
+### Agent Skill
+
+Install the Agent Skill globally:
+
+```sh
+npx skills add https://repos.astrazds.net/astrazds/fjgo.git --skill fjgo -g
+```
+
+That is the full setup. You do not need to clone this repository or run
+`npm install`.
+
+The skill teaches your agent to run the CLI through `npx -y @astrazds/fjgo`.
+The npm package is scoped because unscoped `fjgo` is blocked on the public
+registry. The installed command name remains `fjgo`. The first run downloads
+the matching native release and saves it in a local cache. Later runs reuse
+that copy.
+
+Requirements: Node.js 20 or newer, on Linux or macOS with an x64 or arm64 CPU.
+
+Without Node.js, install a native release archive:
+
+```sh
+curl -LO https://repos.astrazds.net/astrazds/fjgo/releases/download/v1.4.1/fjgo_v1.4.1_linux_amd64.tar.gz
+tar -xzf fjgo_v1.4.1_linux_amd64.tar.gz
+install -Dm755 fjgo_v1.4.1_linux_amd64/fjgo ~/.local/bin/fjgo
+```
+
+Use `darwin` instead of `linux`, and `arm64` instead of `amd64`, when that
+matches the machine. Then run `fjgo` directly instead of `npx -y @astrazds/fjgo`.
+
+### Optional ambient hooks
+
+The skill and the native binary are enough for on-demand use. If you want
+Forgejo context injected at the start of every agent session, install the
+optional hooks after the CLI is on PATH:
+
+```sh
+npx -y @astrazds/fjgo setup hooks --check
+npx -y @astrazds/fjgo setup hooks
+```
+
+You only need the skill or the hooks. Installing both is fine; the hooks add
+live session context, and the skill remains available on demand.
+
+### Codex plugin
+
+This repository is also a validated Codex plugin package. A marketplace can
+point at the repository root to distribute the existing `fjgo` skill with
+plugin presentation metadata and starter prompts. Until a marketplace lists
+it, the Agent Skill command above remains the shortest public installation
+path.
+
+The plugin still runs `npx -y @astrazds/fjgo`; it does not bundle another API client,
+install ambient hooks automatically, provide OAuth, or store credentials.
+See [Codex plugin](docs/codex-plugin.md) for marketplace installation, local
+testing, authentication, and maintenance details.
+
+## Connect to Forgejo
+
+Set your Forgejo host and access token:
+
+```sh
+export FJGO_HOST=forgejo.example.com
+export FJGO_TOKEN=your_access_token
+```
+
+Create the token in your Forgejo account settings. Give it only the permissions
+needed for your task. Do not paste the token into an agent prompt or commit it
+to a file.
+
+## First use
+
+Run these commands inside a repository that has a Forgejo Git remote named
+`origin`:
+
+```sh
+npx -y @astrazds/fjgo -R origin
+npx -y @astrazds/fjgo -R origin doctor
+npx -y @astrazds/fjgo -R origin issue list --state open
+npx -y @astrazds/fjgo -R origin pr list --state open
+npx -y @astrazds/fjgo -R origin run list
+```
+
+`-R origin` reads the repository owner and name from the Git remote. You can
+also choose a repository directly:
+
+```sh
+npx -y @astrazds/fjgo --repo OWNER/REPO repo get
+npx -y @astrazds/fjgo issue list OWNER/REPO --state open
+```
+
+## Make a change safely
+
+Commands that change Forgejo require `--yes`. Preview the request with
+`--dry-run` first:
+
+```sh
+npx -y @astrazds/fjgo -R origin issue create \
+  --title "Fix the login page" \
+  --body "The login button is not working." \
+  --dry-run --yes
+```
+
+If the preview is correct, remove `--dry-run`:
+
+```sh
+npx -y @astrazds/fjgo -R origin issue create \
+  --title "Fix the login page" \
+  --body "The login button is not working." \
+  --yes
+```
+
+More examples:
+
+```sh
+npx -y @astrazds/fjgo -R origin issue view 42 --comments --full
+npx -y @astrazds/fjgo -R origin pr checks 12
+npx -y @astrazds/fjgo -R origin release list
+npx -y @astrazds/fjgo -R origin workflow list
+npx -y @astrazds/fjgo -R origin search issues "login" --state open
+```
+
+Every command has focused help:
+
+```sh
+npx -y @astrazds/fjgo issue --help
+npx -y @astrazds/fjgo issue create --help
+```
+
+## Learn more
+
+- [Wiki manual](https://repos.astrazds.net/astrazds/fjgo/wiki): concise operator
+  guidance published through Forgejo from the reviewed sources in `docs/wiki`.
+- [CLI reference](docs/cli-reference.md): authentication, repository selection,
+  output, command groups, and the full API escape hatch.
+- [Agent setup prompt](docs/agent-setup-prompt.md): a ready-to-paste setup prompt
+  for another coding agent.
+- [Codex plugin](docs/codex-plugin.md): plugin packaging, marketplace
+  installation, authentication boundaries, and validation.
+- [Development guide](docs/development.md): build, test, generate code, and make
+  releases, including the deterministic offline agent-job benchmark and its
+  scenario-run record format. CI runs through `.forgejo/workflows/verify.yml`.
+- [AXI compliance](docs/axi-compliance.md): the agent-friendly interface rules
+  followed by `fjgo`.
+- [Field validation](docs/alpha.md): the v1.4.1 live-testing checklist.
+- [Changelog](CHANGELOG.md): release history.
+
+## License
+
+MIT

package/bin/fjgo.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { run } from "../lib/launcher.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  process.stdout.write(`error: unable to run fjgo: ${error.message}\n`);
+  process.stdout.write("help: check network access or install a native fjgo release\n");
+  process.exitCode = 1;
+});

package/lib/launcher.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
+
+const releaseBase = "https://repos.astrazds.net/astrazds/fjgo/releases/download";
+
+export function releaseTarget(platform = process.platform, arch = process.arch) {
+  const platforms = { darwin: "darwin", linux: "linux" };
+  const architectures = { arm64: "arm64", x64: "amd64" };
+  if (!platforms[platform] || !architectures[arch]) {
+    throw new Error(`unsupported platform ${platform}/${arch}; supported platforms are linux and macOS on x64 or arm64`);
+  }
+  return { os: platforms[platform], arch: architectures[arch] };
+}
+
+export function checksumFor(checksums, archiveName) {
+  for (const line of checksums.split(/\r?\n/)) {
+    const match = line.trim().match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (match && basename(match[2]) === archiveName) {
+      return match[1].toLowerCase();
+    }
+  }
+  throw new Error(`release checksums do not contain ${archiveName}`);
+}
+
+function tarString(block, start, length) {
+  return block.subarray(start, start + length).toString("utf8").replace(/\0.*$/, "");
+}
+
+export function extractBinary(archive, expectedPath) {
+  const tar = gunzipSync(archive);
+  for (let offset = 0; offset + 512 <= tar.length; ) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+    const name = tarString(header, 0, 100);
+    const prefix = tarString(header, 345, 155);
+    const path = prefix ? `${prefix}/${name}` : name;
+    const sizeText = tarString(header, 124, 12).trim();
+    const size = Number.parseInt(sizeText || "0", 8);
+    if (!Number.isSafeInteger(size) || size < 0) throw new Error("release archive has an invalid entry size");
+    const dataStart = offset + 512;
+    const dataEnd = dataStart + size;
+    if (dataEnd > tar.length) throw new Error("release archive is truncated");
+    if (path === expectedPath) return Buffer.from(tar.subarray(dataStart, dataEnd));
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  throw new Error(`release archive does not contain ${expectedPath}`);
+}
+
+async function download(url, fetchImpl) {
+  const response = await fetchImpl(url, { redirect: "follow", signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`download failed with HTTP ${response.status} for ${url}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+export async function ensureBinary(options = {}) {
+  const packagePath = fileURLToPath(new URL("../package.json", import.meta.url));
+  const packageJSON = JSON.parse(await readFile(packagePath, "utf8"));
+  const version = options.version ?? packageJSON.version;
+  const tag = version.startsWith("v") ? version : `v${version}`;
+  const target = releaseTarget(options.platform, options.arch);
+  const archiveName = `fjgo_${tag}_${target.os}_${target.arch}.tar.gz`;
+  const entryName = `fjgo_${tag}_${target.os}_${target.arch}/fjgo`;
+  const cacheRoot = options.cacheDir ?? process.env.FJGO_NPX_CACHE_DIR ?? join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "fjgo");
+  const binary = join(cacheRoot, tag, `${target.os}-${target.arch}`, "fjgo");
+
+  try {
+    await chmod(binary, 0o755);
+    return binary;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+
+  const base = (options.baseUrl ?? process.env.FJGO_NPX_RELEASE_BASE ?? releaseBase).replace(/\/$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const [archive, checksumsBuffer] = await Promise.all([
+    download(`${base}/${tag}/${archiveName}`, fetchImpl),
+    download(`${base}/${tag}/checksums.txt`, fetchImpl),
+  ]);
+  const expected = checksumFor(checksumsBuffer.toString("utf8"), archiveName);
+  const actual = createHash("sha256").update(archive).digest("hex");
+  if (actual !== expected) throw new Error(`checksum mismatch for ${archiveName}`);
+
+  const contents = extractBinary(archive, entryName);
+  await mkdir(dirname(binary), { recursive: true });
+  const temporary = `${binary}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, contents, { mode: 0o755 });
+    await rename(temporary, binary);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+  return binary;
+}
+
+export async function run(args) {
+  const binary = await ensureBinary();
+  const child = spawn(binary, args, { stdio: "inherit", env: process.env });
+  await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (signal) process.kill(process.pid, signal);
+      else process.exitCode = code ?? 1;
+      resolve();
+    });
+  });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@astrazds/fjgo",
+  "version": "1.4.1",
+  "description": "Agent-first CLI and API client for Forgejo",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "fjgo": "bin/fjgo.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://repos.astrazds.net/astrazds/fjgo.git"
+  },
+  "homepage": "https://repos.astrazds.net/astrazds/fjgo",
+  "bugs": {
+    "url": "https://repos.astrazds.net/astrazds/fjgo/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepack": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@openai/codex": "0.145.0"
+  }
+}