jackwener / jackwener/OpenCLI

docs/ excluded from npm tarball — README 'Extending OpenCLI' link is dead for installed users; override mechanism undiscoverable

Open Beginner friendly
#1,918 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
29.3k
Forks
2.9k
Avg merge
15h 36m
Merged PRs (30d)
70

Description

## Problem

`package.json`'s `files` field ships `dist/src/`, `clis/`, `cli-manifest.json`, `scripts/`, `README.md`, `LICENSE` — **`docs/` is excluded**. But `README.md` ("## Extending OpenCLI") links to `./docs/guide/extending-opencli.md`, a repo-relative path that resolves only on GitHub. For anyone who `npm i -g @jackwener/opencli` and reads the bundled README, that link is dead.

That guide is the **only** documentation of the "Local overrides for official adapters" flow (`opencli adapter eject` / `reset` / `status` + sparse single-file override). The CLI exposes `opencli adapter --help`, but the *when/why/how* — sparse override semantics, update survival, `verify` running the override, the `doctor` shadow warning — lives solely in the unshipped guide.

## Why it matters (agent use case)

Driving opencli from an AI agent off a fresh npm install: the agent sees `adapter eject` in `--help` at best, with no conceptual guide, and the companion skills (`opencli-adapter-author`, `opencli-usage`) don't mention the official-adapter override path either. Result: agents re-fork whole adapters or — worse — edit files inside `node_modules/@jackwener/opencli/clis/`, which the next `npm -g` upgrade silently overwrites. (Hit exactly this during a customization attempt on a bundled adapter.)

## Suggested fix (either)

1. Add `docs/` (or `docs/guide/`) to `package.json` `files` so the tarball ships it and the README link resolves locally; **or**
2. Make the README "Extending OpenCLI" section self-contained — inline a short `adapter eject`/`reset`/`status` quickref so it doesn't depend on an unshipped file.

Option 1 is lower-effort and keeps a single source of truth.

— Written by Claude Code (Opus 4.8) on behalf of @0reo

Contributor guide

Open the contributing guide

Research direction

Inspect package.json's files field, README.md's "Extending OpenCLI" section, and docs/guide/extending-opencli.md. Start by checking how the npm package includes documentation and how the README link resolves after installation; done means installed users can reach the override guidance without a dead link or missing guide.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, nodejs
Domain
build-system, cli, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.