@mbe24/99problems 0.1.1 → 0.3.0

package/README.md

@@ -1,118 +1,154 @@
 # 99problems
 
 [![CI](https://github.com/mbe24/99problems/actions/workflows/ci.yml/badge.svg)](https://github.com/mbe24/99problems/actions/workflows/ci.yml)
+[![Man Drift](https://github.com/mbe24/99problems/actions/workflows/man-drift.yml/badge.svg)](https://github.com/mbe24/99problems/actions/workflows/man-drift.yml)
 [![npm](https://img.shields.io/npm/v/@mbe24/99problems?color=7C3AED&label=npm)](https://www.npmjs.com/package/@mbe24/99problems)
 [![crates.io](https://img.shields.io/crates/v/problems99?color=7C3AED&label=crates.io)](https://crates.io/crates/problems99)
 ![platforms](https://img.shields.io/badge/platforms-win%20%7C%20linux%20%7C%20macos-7C3AED)
 [![License Info](http://img.shields.io/badge/license-Apache%20License%20v2.0-orange.svg)](https://raw.githubusercontent.com/mbe24/99problems/main/LICENSE)
 
-> AI-friendly access to GitHub issues.
-
-Fetch GitHub issue conversations as structured JSON or YAML — ready for LLM pipelines, RAG, and bulk analysis. Uses the same search syntax as the GitHub web UI.
-
-
+`99problems` fetches issue and pull request conversations (including comments) from GitHub, GitLab, Jira, and Bitbucket.
+It supports machine-readable output (`json`, `yaml`, `jsonl`/`ndjson`) and a human-readable `text` format.
 
 ## Installation
 
 ```bash
 npm install -g @mbe24/99problems
+# or
+cargo install problems99
 ```
 
-Or via cargo:
+## Quick Start
 
 ```bash
-cargo install problems99
-```
+# Fetch one GitHub issue
+99problems get --repo schemaorg/schemaorg --id 1842
 
-Pre-built binaries are available for Windows x64, Linux x64, Linux ARM64, macOS Intel, and macOS Apple Silicon. No runtime dependencies.
+# Fetch one PR with inline review comments
+99problems get --repo github/gitignore --id 2402 --type pr --include-review-comments
 
-## Usage
+# Search GitLab issues
+99problems get --platform gitlab -q "repo:veloren/veloren is:issue state:closed terrain"
 
-```bash
-# Fetch all closed issues mentioning "Event" from a repo
-99problems -q "is:issue state:closed Event repo:schemaorg/schemaorg" -o output.json
+# Fetch Jira issue by key
+99problems get --platform jira --id CLOUD-12817
 
-# Fetch a single issue
-99problems --repo schemaorg/schemaorg --issue 1842
+# Fetch Bitbucket Cloud PR by ID
+99problems get --platform bitbucket --deployment cloud --repo workspace/repo_slug --id 1 --type pr
 
-# YAML output
-99problems -q "state:open label:bug repo:owner/repo" --format yaml
+# Fetch Bitbucket Data Center PR by ID
+99problems get --platform bitbucket --deployment selfhosted --url https://bitbucket.mycompany.com --repo PROJECT/repo_slug --id 1
 
-# Pipe into jq
-99problems -q "state:closed repo:owner/repo" | jq '.[].title'
+# Stream as JSON Lines for pipelines
+99problems get -q "repo:github/gitignore is:issue state:open" --output-mode stream --format jsonl
 ```
 
-## Output
-
-Each result is a conversation object with the issue body and all comments:
-
-```json
-[
-  {
-    "id": 1842,
-    "title": "Event schema improvements",
-    "body": "Issue body text...",
-    "url": "https://github.com/schemaorg/schemaorg/issues/1842",
-    "state": "closed",
-    "created_at": "2019-04-01T12:00:00Z",
-    "comments": [
-      {
-        "author": "octocat",
-        "body": "Comment text...",
-        "created_at": "2019-04-02T08:00:00Z"
-      }
-    ]
-  }
-]
+## Commands
+
+```text
+99problems get [OPTIONS]               Fetch issue and pull request conversations
+99problems config <SUBCOMMAND>         Inspect and edit .99problems configuration
+99problems completions <SHELL>         Generate shell completion scripts
+99problems man [OPTIONS]               Generate man pages (stdout or files)
+```
+
+Global options:
+
+```text
+-v, --verbose              Increase diagnostics (-v, -vv, -vvv)
+-Q, --quiet                Show errors only
+    --error-format <FMT>   Error output: text|json (default: text)
+-h, --help                 Print help
+-V, --version              Print version
 ```
 
 ## Configuration
 
-`99problems` reads TOML dotfiles so you don't have to repeat flags on every run.
+`99problems` uses instance-based TOML config from:
 
-| File | Purpose |
-|---|---|
-| `~/.99problems` | Global defaults (token, preferred repo, etc.) |
-| `./.99problems` | Per-project overrides |
+- `~/.99problems`
+- `./.99problems`
 
-Example `~/.99problems`:
+Example:
 
 ```toml
-token = "ghp_your_personal_access_token"
+default_instance = "work-gitlab"
+
+[instances.github]
+platform = "github"
+repo = "owner/repo"
+token = "ghp_your_token"
+
+[instances.work-gitlab]
+platform = "gitlab"
+url = "https://gitlab.mycompany.com"
+repo = "group/project"
+token = "glpat_your_token"
+
+[instances.work-jira]
+platform = "jira"
+url = "https://jira.mycompany.com"
+repo = "CPQ"
+token = "atlassian_api_token"
+account_email = "user@example.com"
+
+[instances.bitbucket-cloud]
+platform = "bitbucket"
+deployment = "cloud"
+repo = "workspace/repo_slug"
+token = "username:app_password"
+
+[instances.bitbucket-dc]
+platform = "bitbucket"
+deployment = "selfhosted"
+url = "https://bitbucket.mycompany.com"
+repo = "PROJECT/repo_slug"
+token = "pat_or_bearer_token"
 ```
 
-Example `./.99problems` in a project directory:
+Bitbucket support is pull-request only; when `--type` is omitted, `99problems` defaults to PRs.
+For Bitbucket Cloud, use an app-password, repository access token, or workspace-level access token (premium feature) in `token`.
 
-```toml
-repo  = "owner/my-repo"
-state = "closed"
-```
+Selection order: `--instance` -> single configured instance -> `default_instance`.
 
-Token is resolved in this order: `--token` flag → `GITHUB_TOKEN` env var → `./.99problems` → `~/.99problems`. Without a token the GitHub API rate limit is 60 requests/hour; with one it's 5,000/hour.
+## Man Pages
 
-## Options
+Generate and print root man page:
 
+```bash
+99problems man
 ```
-Options:
-  -q, --query <QUERY>      Full GitHub search query (web UI syntax)
-      --repo <REPO>        Shorthand for "repo:owner/name"
-      --state <STATE>      Shorthand for "state:open|closed"
-      --labels <LABELS>    Comma-separated labels, e.g. "bug,help wanted"
-      --issue <ISSUE>      Fetch a single issue by number (requires --repo)
-      --source <SOURCE>    Data source [default: github-issues]
-      --format <FORMAT>    Output format: json | yaml [default: json]
-  -o, --output <FILE>      Write to file instead of stdout
-      --token <TOKEN>      GitHub personal access token
-  -h, --help               Print help
-  -V, --version            Print version
+
+Generate all pages to disk:
+
+```bash
+99problems man --output docs/man --section 1
 ```
 
-## Use cases
+Committed man pages live in `docs/man/`.
+The `Man Drift` workflow verifies generated output stays in sync with committed files.
+
+## Output Modes
+
+`get` supports two orthogonal controls:
+
+- `--format`: `json`, `yaml`, `jsonl`, `ndjson` (alias of `jsonl`), `text`
+- `--output-mode`: `auto`, `batch`, `stream` (or `--stream`)
 
-- **LLM context / RAG** — load issue history into a vector store or prompt
-- **Issue triage** — process closed issues in bulk with Python or JavaScript
-- **Dataset generation** — build labelled datasets from GitHub discussions
-- **Changelog automation** — extract closed issues for release notes
+Defaults:
+
+- TTY stdout: `--format text`, `--output-mode auto` (resolved to streaming)
+- piped stdout / file output: `--format jsonl`, `--output-mode auto` (resolved to streaming)
+
+Use `--output-mode batch` when you want all-or-nothing output at the end.
+
+## Shell Completions
+
+```bash
+99problems completions bash
+99problems completions zsh
+99problems completions powershell
+```
 
 ## Contributing
 
@@ -122,3 +158,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 See [LICENSE](LICENSE).
 
+Copyright (c) 2026 Mikael Beyene

package/docs/man/99problems-completions.1

@@ -0,0 +1,31 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems-completions 1  "completions " 
+.SH NAME
+99problems\-completions \- Generate shell completion script and print it to stdout
+.SH SYNOPSIS
+\fB99problems completions\fR [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-Q\fR|\fB\-\-quiet\fR] [\fB\-\-error\-format\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fISHELL\fR> 
+.SH DESCRIPTION
+Generate shell completion script and print it to stdout
+.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase diagnostic verbosity (\-v, \-vv, \-vvv)
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR
+Suppress non\-error diagnostics
+.TP
+\fB\-\-error\-format\fR \fI<ERROR_FORMAT>\fR [default: text]
+Error output format
+.br
+
+.br
+[\fIpossible values: \fRtext, json]
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.TP
+<\fISHELL\fR>
+
+.br
+[\fIpossible values: \fRbash, zsh, fish, powershell, elvish]

package/docs/man/99problems-config.1

@@ -0,0 +1,50 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems-config 1  "config " 
+.SH NAME
+99problems\-config \- Inspect and edit .99problems configuration
+.SH SYNOPSIS
+\fB99problems config\fR [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-Q\fR|\fB\-\-quiet\fR] [\fB\-\-error\-format\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Inspect and edit .99problems configuration
+.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase diagnostic verbosity (\-v, \-vv, \-vvv)
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR
+Suppress non\-error diagnostics
+.TP
+\fB\-\-error\-format\fR \fI<ERROR_FORMAT>\fR [default: text]
+Error output format
+.br
+
+.br
+[\fIpossible values: \fRtext, json]
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH SUBCOMMANDS
+.TP
+99problems\-config\-path(1)
+Print config file path for a scope
+.TP
+99problems\-config\-list(1)
+List all configured keys in a scope
+.TP
+99problems\-config\-get(1)
+Read one configured key
+.TP
+99problems\-config\-set(1)
+Set a configured key
+.TP
+99problems\-config\-unset(1)
+Unset a configured key
+.TP
+99problems\-config\-help(1)
+Print this message or the help of the given subcommand(s)
+.SH EXTRA
+Examples:
+  99problems config list
+  99problems config set default_instance work\-gitlab
+  99problems config get instances.work\-gitlab.repo \-\-scope resolved

package/docs/man/99problems-get.1

@@ -0,0 +1,114 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems-get 1  "get " 
+.SH NAME
+99problems\-get \- Fetch issue and pull request conversations
+.SH SYNOPSIS
+\fB99problems get\fR [\fB\-q\fR|\fB\-\-query\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-Q\fR|\fB\-\-quiet\fR] [\fB\-r\fR|\fB\-\-repo\fR] [\fB\-\-error\-format\fR] [\fB\-s\fR|\fB\-\-state\fR] [\fB\-l\fR|\fB\-\-labels\fR] [\fB\-a\fR|\fB\-\-author\fR] [\fB\-S\fR|\fB\-\-since\fR] [\fB\-m\fR|\fB\-\-milestone\fR] [\fB\-i\fR|\fB\-\-id\fR] [\fB\-p\fR|\fB\-\-platform\fR] [\fB\-I\fR|\fB\-\-instance\fR] [\fB\-u\fR|\fB\-\-url\fR] [\fB\-\-deployment\fR] [\fB\-t\fR|\fB\-\-type\fR] [\fB\-f\fR|\fB\-\-format\fR] [\fB\-\-output\-mode\fR] [\fB\-\-stream\fR] [\fB\-R\fR|\fB\-\-include\-review\-comments\fR] [\fB\-\-no\-comments\fR] [\fB\-o\fR|\fB\-\-output\fR] [\fB\-k\fR|\fB\-\-token\fR] [\fB\-\-account\-email\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Fetch issue and pull request conversations
+.SH OPTIONS
+.TP
+\fB\-q\fR, \fB\-\-query\fR \fI<QUERY>\fR
+Full search query (same syntax as the platform\*(Aqs web UI search bar) e.g. "state:closed Event repo:owner/repo"
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase diagnostic verbosity (\-v, \-vv, \-vvv)
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR
+Suppress non\-error diagnostics
+.TP
+\fB\-r\fR, \fB\-\-repo\fR \fI<REPO>\fR
+Shorthand for adding "repo:owner/repo" to the query (alias: \-\-project)
+.TP
+\fB\-\-error\-format\fR \fI<ERROR_FORMAT>\fR [default: text]
+Error output format
+.br
+
+.br
+[\fIpossible values: \fRtext, json]
+.TP
+\fB\-s\fR, \fB\-\-state\fR \fI<STATE>\fR
+Shorthand for adding "state:open|closed" to the query
+.TP
+\fB\-l\fR, \fB\-\-labels\fR \fI<LABELS>\fR
+Shorthand for comma\-separated labels, e.g. "bug,enhancement"
+.TP
+\fB\-a\fR, \fB\-\-author\fR \fI<AUTHOR>\fR
+Filter by issue/PR author
+.TP
+\fB\-S\fR, \fB\-\-since\fR \fI<SINCE>\fR
+Only include items created on or after this date (YYYY\-MM\-DD), e.g. "2024\-01\-01"
+.TP
+\fB\-m\fR, \fB\-\-milestone\fR \fI<MILESTONE>\fR
+Filter by milestone title or number
+.TP
+\fB\-i\fR, \fB\-\-id\fR \fI<ID>\fR
+Fetch a single issue/PR by identifier (bypasses search)
+.TP
+\fB\-p\fR, \fB\-\-platform\fR \fI<PLATFORM>\fR
+Platform adapter to fetch from (used directly in CLI\-only mode)
+.br
+
+.br
+[\fIpossible values: \fRgithub, gitlab, jira, bitbucket]
+.TP
+\fB\-I\fR, \fB\-\-instance\fR \fI<INSTANCE>\fR
+Named instance alias from .99problems ([instances.<alias>])
+.TP
+\fB\-u\fR, \fB\-\-url\fR \fI<URL>\fR
+Override platform base URL for one\-off runs
+.TP
+\fB\-\-deployment\fR \fI<DEPLOYMENT>\fR
+Bitbucket deployment type (required for \-\-platform bitbucket)
+.br
+
+.br
+[\fIpossible values: \fRcloud, selfhosted]
+.TP
+\fB\-t\fR, \fB\-\-type\fR \fI<KIND>\fR
+Content type to fetch (Bitbucket supports pull requests only; omitted type defaults to pr)
+.br
+
+.br
+[\fIpossible values: \fRissue, pr]
+.TP
+\fB\-f\fR, \fB\-\-format\fR \fI<FORMAT>\fR
+Output format (default: text for TTY, jsonl for piped/file output)
+.br
+
+.br
+[\fIpossible values: \fRjson, yaml, jsonl, ndjson, text]
+.TP
+\fB\-\-output\-mode\fR \fI<OUTPUT_MODE>\fR
+Output behavior mode
+.br
+
+.br
+[\fIpossible values: \fRauto, batch, stream]
+.TP
+\fB\-\-stream\fR
+Shorthand for \-\-output\-mode stream
+.TP
+\fB\-R\fR, \fB\-\-include\-review\-comments\fR
+Include pull request review comments (inline code comments)
+.TP
+\fB\-\-no\-comments\fR
+Skip fetching comments (faster, smaller output)
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+Write output to a file (default: stdout)
+.TP
+\fB\-k\fR, \fB\-\-token\fR \fI<TOKEN>\fR
+Personal access token (overrides env var and dotfile)
+.TP
+\fB\-\-account\-email\fR \fI<ACCOUNT_EMAIL>\fR
+Account email used with Jira API\-token basic auth
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help
+.SH EXTRA
+Examples:
+  99problems get \-\-repo schemaorg/schemaorg \-\-id 1842
+  99problems get \-\-repo github/gitignore \-\-id 2402 \-\-type pr \-\-include\-review\-comments
+  99problems get \-q "repo:owner/repo state:open label:bug" \-\-output\-mode stream \-\-format jsonl

package/docs/man/99problems-help.1

@@ -0,0 +1,25 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems-help 1  "help " 
+.SH NAME
+99problems\-help \- Print this message or the help of the given subcommand(s)
+.SH SYNOPSIS
+\fB99problems help\fR [\fIsubcommands\fR]
+.SH DESCRIPTION
+Print this message or the help of the given subcommand(s)
+.SH SUBCOMMANDS
+.TP
+99problems\-help\-get(1)
+Fetch issue and pull request conversations
+.TP
+99problems\-help\-config(1)
+Inspect and edit .99problems configuration
+.TP
+99problems\-help\-completions(1)
+Generate shell completion script and print it to stdout
+.TP
+99problems\-help\-man(1)
+Generate and print/write man pages
+.TP
+99problems\-help\-help(1)
+Print this message or the help of the given subcommand(s)

package/docs/man/99problems-man.1

@@ -0,0 +1,32 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems-man 1  "man " 
+.SH NAME
+99problems\-man \- Generate and print/write man pages
+.SH SYNOPSIS
+\fB99problems man\fR [\fB\-o\fR|\fB\-\-output\fR] [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-Q\fR|\fB\-\-quiet\fR] [\fB\-\-section\fR] [\fB\-\-error\-format\fR] [\fB\-h\fR|\fB\-\-help\fR] 
+.SH DESCRIPTION
+Generate and print/write man pages
+.SH OPTIONS
+.TP
+\fB\-o\fR, \fB\-\-output\fR \fI<OUTPUT>\fR
+Output directory to write generated man pages
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase diagnostic verbosity (\-v, \-vv, \-vvv)
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR
+Suppress non\-error diagnostics
+.TP
+\fB\-\-section\fR \fI<SECTION>\fR [default: 1]
+Man section number to use in generated filenames
+.TP
+\fB\-\-error\-format\fR \fI<ERROR_FORMAT>\fR [default: text]
+Error output format
+.br
+
+.br
+[\fIpossible values: \fRtext, json]
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help

package/docs/man/99problems.1

@@ -0,0 +1,52 @@
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH 99problems 1  "99problems 0.2.0" 
+.SH NAME
+99problems \- Fetch issue and pull request conversations
+.SH SYNOPSIS
+\fB99problems\fR [\fB\-v\fR|\fB\-\-verbose\fR]... [\fB\-Q\fR|\fB\-\-quiet\fR] [\fB\-\-error\-format\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] <\fIsubcommands\fR>
+.SH DESCRIPTION
+Fetch issue and pull request conversations from GitHub, GitLab, and Jira.
+.SH OPTIONS
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+Increase diagnostic verbosity (\-v, \-vv, \-vvv)
+.TP
+\fB\-Q\fR, \fB\-\-quiet\fR
+Suppress non\-error diagnostics
+.TP
+\fB\-\-error\-format\fR \fI<ERROR_FORMAT>\fR [default: text]
+Error output format
+.br
+
+.br
+[\fIpossible values: \fRtext, json]
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Print help (see a summary with \*(Aq\-h\*(Aq)
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+Print version
+.SH SUBCOMMANDS
+.TP
+99problems\-get(1)
+Fetch issue and pull request conversations
+.TP
+99problems\-config(1)
+Inspect and edit .99problems configuration
+.TP
+99problems\-completions(1)
+Generate shell completion script and print it to stdout
+.TP
+99problems\-man(1)
+Generate and print/write man pages
+.TP
+99problems\-help(1)
+Print this message or the help of the given subcommand(s)
+.SH EXTRA
+Examples:
+  99problems get \-\-repo schemaorg/schemaorg \-\-id 1842
+  99problems get \-q "repo:github/gitignore is:pr 2402" \-\-include\-review\-comments
+  99problems man \-\-output docs/man
+.SH VERSION
+v0.2.0

package/npm/install.js

@@ -1,5 +1,7 @@
-// postinstall: verify the platform binary is available.
-const { execSync } = require("child_process");
+// postinstall: verify the platform binary is available and install shell completions when possible.
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
 const PLATFORMS = {
@@ -19,8 +21,93 @@ if (!pkg) {
 }
 
 try {
-  require.resolve(`${pkg}/bin/99problems${process.platform === "win32" ? ".exe" : ""}`);
+  const binaryName = process.platform === "win32" ? "99problems.exe" : "99problems";
+  const binaryPath = require.resolve(`${pkg}/bin/${binaryName}`);
   console.log(`[99problems] Binary found for ${key}.`);
+  installCompletions(binaryPath);
 } catch {
   console.warn(`[99problems] Optional dependency ${pkg} not installed (this is OK if you're building from source).`);
 }
+
+function detectShell() {
+  const shellPath = (process.env.SHELL || "").toLowerCase();
+  if (shellPath.includes("bash")) return "bash";
+  if (shellPath.includes("zsh")) return "zsh";
+  if (shellPath.includes("fish")) return "fish";
+  if (shellPath.includes("elvish")) return "elvish";
+
+  // Best-effort PowerShell detection on Windows
+  if (
+    process.platform === "win32" &&
+    ((process.env.ComSpec || "").toLowerCase().includes("powershell") ||
+      process.env.PSModulePath)
+  ) {
+    return "powershell";
+  }
+
+  return null;
+}
+
+function completionTarget(shell) {
+  const home = os.homedir();
+  switch (shell) {
+    case "bash":
+      return {
+        path: path.join(home, ".local", "share", "bash-completion", "completions", "99problems"),
+        hint: 'Open a new shell, or run: source ~/.local/share/bash-completion/completions/99problems',
+      };
+    case "zsh":
+      return {
+        path: path.join(home, ".zfunc", "_99problems"),
+        hint:
+          "Ensure '~/.zfunc' is in fpath and compinit is enabled (then restart shell).",
+      };
+    case "fish":
+      return {
+        path: path.join(home, ".config", "fish", "completions", "99problems.fish"),
+        hint: "Open a new fish shell session.",
+      };
+    default:
+      return null;
+  }
+}
+
+function installCompletions(binaryPath) {
+  if (process.env.NINETY_NINE_PROBLEMS_SKIP_COMPLETIONS === "1") {
+    return;
+  }
+
+  const shell = detectShell();
+  if (!shell) {
+    console.log(
+      "[99problems] Could not detect your shell. Generate completions manually, e.g. '99problems completions bash'."
+    );
+    return;
+  }
+
+  const target = completionTarget(shell);
+  if (!target) {
+    console.log(
+      `[99problems] Shell '${shell}' detected. Auto-install is not supported; generate manually with '99problems completions ${shell}'.`
+    );
+    return;
+  }
+
+  try {
+    const script = execFileSync(binaryPath, ["completions", shell], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    fs.mkdirSync(path.dirname(target.path), { recursive: true });
+    fs.writeFileSync(target.path, script, "utf8");
+    console.log(`[99problems] ${shell} completions installed at ${target.path}`);
+    console.log(`[99problems] ${target.hint}`);
+  } catch (err) {
+    console.warn(
+      `[99problems] Could not install ${shell} completions automatically: ${err.message}`
+    );
+    console.warn(
+      `[99problems] You can still generate them manually with: 99problems completions ${shell}`
+    );
+  }
+}