@mbe24/99problems 0.2.0 → 0.3.0

package/README.md

@@ -1,134 +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.
-
-`99problems` is a command-line tool that fetches GitHub issue conversations — including all comments — and exports them as structured **JSON** or **YAML**. It uses the same search syntax as the GitHub web UI, making it easy to export, analyse, or feed GitHub issues into LLM pipelines, RAG systems, vector stores, and data analysis workflows.
-
-Built in Rust. Distributed as a single binary via npm and crates.io. No runtime dependencies.
+`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.
+# 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
-# Export all closed issues mentioning "Event" to JSON
-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 with all its comments
-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
 
-# Export open bug issues as YAML
-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 for further processing
-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 containing 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)
 ```
 
-## Configuration
+Global options:
 
-`99problems` reads TOML dotfiles so you don't have to repeat flags on every run.
+```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
+```
 
-| File | Purpose |
-|---|---|
-| `~/.99problems` | Global defaults (token, preferred repo, etc.) |
-| `./.99problems` | Per-project overrides |
+## Configuration
 
-Example `~/.99problems`:
+`99problems` uses instance-based TOML config from:
 
-```toml
-[github]
-token = "ghp_your_personal_access_token"
-```
+- `~/.99problems`
+- `./.99problems`
 
-Example `./.99problems` in a project directory:
+Example:
 
 ```toml
-repo  = "owner/my-repo"
-state = "closed"
-```
+default_instance = "work-gitlab"
 
-For self-hosted GitLab:
+[instances.github]
+platform = "github"
+repo = "owner/repo"
+token = "ghp_your_token"
 
-```toml
+[instances.work-gitlab]
 platform = "gitlab"
-
-[gitlab]
+url = "https://gitlab.mycompany.com"
+repo = "group/project"
 token = "glpat_your_token"
-url   = "https://gitlab.mycompany.com"
+
+[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"
 ```
 
-Token is resolved in this order: `--token` flag → `GITHUB_TOKEN`/`GITLAB_TOKEN`/`BITBUCKET_TOKEN` env var → `./.99problems` → `~/.99problems`. Without a token the GitHub API rate limit is 60 requests/hour; with one it's 5,000/hour.
+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`.
 
-## Options
+Selection order: `--instance` -> single configured instance -> `default_instance`.
 
+## Man Pages
+
+Generate and print root man page:
+
+```bash
+99problems man
 ```
-Options:
-  -q, --query <QUERY>        Full search query (platform 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"
-      --author <AUTHOR>      Filter by issue/PR author
-      --since <DATE>         Only items created on or after YYYY-MM-DD
-      --milestone <NAME>     Filter by milestone title or number
-      --issue <ISSUE>        Fetch a single issue by number (requires --repo)
-      --platform <PLATFORM>  Platform: github | gitlab | bitbucket [default: github]
-      --type <TYPE>          Content type: issue | pr [default: issue]
-      --format <FORMAT>      Output format: json | yaml [default: json]
-  -o, --output <FILE>        Write to file instead of stdout
-      --token <TOKEN>        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:
 
-- **LLM context / RAG** — export issue history into a vector store or use as prompt context
-- **Issue triage and analysis** — bulk-process GitHub issues with Python, JavaScript, or any data tool
-- **Training data generation** — build labelled datasets from GitHub discussions and bug reports
-- **Changelog and release notes** — extract closed issues for automated release documentation
-- **Knowledge base indexing** — crawl project issue trackers for search and retrieval systems
+- `--format`: `json`, `yaml`, `jsonl`, `ndjson` (alias of `jsonl`), `text`
+- `--output-mode`: `auto`, `batch`, `stream` (or `--stream`)
+
+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
 
@@ -137,3 +157,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 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}`
+    );
+  }
+}