Package 'ghqc'

Run the ghqc UI as a background job

Description

Starts the ghqc web UI as a supervised background R process and opens it in the browser. Any previously running ghqc server is stopped first. Use ghqc_stop() to stop the server, ghqc_status() to check its status, or ghqc_reconnect() to reopen the browser tab without restarting the server.

Usage

ghqc(
  directory = here::here(),
  port = NULL,
  config_dir = NULL,
  ipv4_only = FALSE,
  log_level = Sys.getenv("GHQC_LOG_LEVEL", "TRACE")
)

Arguments

directory	Path to the project directory. Defaults to the project root as determined by here::here().
port	Integer port to bind the server to. If NULL (default), a random available port is selected automatically.
config_dir	Path to the ghqc configuration directory. If NULL (default), ghqc uses its default configuration discovery logic.
ipv4_only	Force IPv4-only bind and loopback URL
log_level	Level of logging the server runs with. Recommended to leave as TRACE since ghqc_log() will filter levels.

Value

Called for its side effect of starting the server and opening the browser. Returns NULL invisibly.

Examples

## Not run: 
# Start with defaults (project root, random port)
ghqc()

# Start on a specific port
ghqc(port = 8080)

# Start for a subdirectory with a custom config location
ghqc(directory = "analysis", config_dir = "~/.config/ghqc")

## End(Not run)

---

Install or upgrade the ghqc binary

Description

Downloads and installs the ghqc command-line binary using the bundled platform install script. On Linux and macOS, the binary is installed to ⁠~/.local/bin⁠. On Windows, it is installed to ⁠%LOCALAPPDATA%/Programs/ghqc⁠.

Usage

ghqc_install(version = NULL)

Arguments

version

Optional release tag to install, such as "v0.4.1". If omitted, the latest available release is installed.

Details

If version is not supplied and ghqc is already installed, the local version is compared to the latest GitHub release. When running interactively and a newer version is available, the user is prompted to confirm the upgrade before proceeding. If version is supplied, that specific release is installed instead.

After a successful install, the install directory is added to PATH for the current R session if it is not already present.

Value

NULL invisibly.

Examples

## Not run: 
ghqc_install()
ghqc_install(version = "v0.7.0")

## End(Not run)

---

Stream logs from the running ghqc server to the console

Description

Blocks the R session and prints server log output as it arrives. Press Ctrl+C (or Escape in RStudio/Positron) to stop streaming.

Usage

ghqc_log(log_level = Sys.getenv("GHQC_LOG_LEVEL", "DEBUG"), interval = 0.2)

Arguments

log_level	Logging filter level
interval	Seconds to wait for output before checking again.

---

Reopen the ghqc UI in the browser

Description

Opens a browser tab pointing to a ghqc server that is already running in the background. This is useful after accidentally closing the browser tab without stopping the server. If no server is running, a message is printed instead.

Usage

ghqc_reconnect()

Value

The stored server URL invisibly, or NULL invisibly if no server is running.

Examples

## Not run: 
ghqc()
ghqc_reconnect()

## End(Not run)

---

Get the latest released ghqc version from GitHub

Description

Queries the GitHub Releases API for the a2-ai/ghqctoolkit repository and returns the tag name of the latest release (e.g. "v0.4.2"). Returns NULL invisibly and prints a warning if the request fails (e.g. due to no internet access or rate limiting).

Usage

ghqc_remote_version()

Value

A character string with the latest release tag (e.g. "v0.4.2"), or NULL invisibly if the version could not be determined.

Examples

## Not run: 
ghqc_remote_version()

## End(Not run)

---

Print a situation report for ghqc and the current project

Description

Collects and displays diagnostic information about the ghqc binary, the currently running ghqc background server (if any), and the git repository for the given directory (owner, repo, branch, and milestones). It also reports authentication state for the repository host. Optionally it reports on the ghqc configuration (checklists, options, etc.).

Usage

ghqc_sitrep(
  directory = here::here(),
  config_dir = NULL,
  with_configuration = FALSE
)

Arguments

directory	Path to the project directory. Defaults to the project root as determined by here::here().
config_dir	Path to the ghqc configuration directory. If NULL (default), ghqc uses its default configuration discovery logic.
with_configuration	Logical. If TRUE, include a section describing the ghqc configuration (checklists, options). Defaults to FALSE.

Value

The raw sitrep data list returned by ⁠ghqc sitrep --json⁠, invisibly. The primary purpose of this function is its printed output.

Examples

## Not run: 
# Basic sitrep
ghqc_sitrep()

# Include configuration details
ghqc_sitrep(with_configuration = TRUE)

## End(Not run)

---

Check the status of the ghqc background server

Description

Reports whether the server started by ghqc() is currently running and, if so, prints its URL.

Usage

ghqc_status()

Value

The stored server URL invisibly, or NULL invisibly if no server has been started this session.

Examples

## Not run: 
ghqc()
ghqc_status()

## End(Not run)

---

Stop the running ghqc background server

Description

Kills the supervised background process started by ghqc(). If no server is running, a message is printed and the function returns silently.

Usage

ghqc_stop()

Value

NULL invisibly.

Examples

## Not run: 
ghqc()
ghqc_stop()

## End(Not run)

---

Get the locally installed ghqc version

Description

Runs ghqc --version and returns the version string. Errors if the ghqc binary is not installed; run ghqc_install() first.

Usage

ghqc_version()

Value

A character string containing the version number (e.g. "0.4.2").

Examples

## Not run: 
ghqc_version()

## End(Not run)

---