skissue 0.1.11

package/README.md

@@ -0,0 +1,132 @@
+# skissue
+
+CLI to **install and sync agent skills** from a **GitHub registry** or a **local directory** (e.g. a monorepo whose root contains **`registry/`** and **`registry.json`**). On the **consumer**, skills are installed under **`skillsRoot`** (default **`.agents/skills/<skill-id>/`**, each with **`SKILL.md`**). Configuration and lock state live under **`.skill-issue/`** (committable; no secrets).
+
+**This repository** contains the **CLI** (`src/`) and a **harness** (`harness/`) — TypeScript checks for this repo's docs, indexes, and `src/` layout. The **hosted skill catalog** (`registry.json` + `registry/<skill-id>/`) lives in the separate **skill-registry** repository. **`.agents/`** holds **agent rules** and mirrored skill docs for this repo only — it is **not** the installable registry.
+
+## Structure
+
+| Path                   | Role                                                                                           |
+| ---------------------- | ---------------------------------------------------------------------------------------------- |
+| [AGENTS.md](AGENTS.md) | Agent entry point                                                                              |
+| [harness/](harness/)   | CI checks (`harness/runner.ts`, `npm run check:all`); see [harness/INDEX.md](harness/INDEX.md) |
+| [.agents/](.agents/)   | Rules for maintaining this repo (not the skill-registry payload)                               |
+| [docs/](docs/)         | Harness (`HARNESS.md`), architecture (`ARCHITECTURE.md`), INDEX format                         |
+| [src/](src/)           | skissue CLI source                                                                             |
+| [scripts/](scripts/)   | `install.sh` for global install from a clone                                                   |
+
+## Requirements
+
+- **Node** 24+ (see `.nvmrc`)
+- **git** on your `PATH`
+- For **remote** registries: access via **`GITHUB_TOKEN`** / **`GH_TOKEN`**, or **git credentials** / **`gh auth`**. **Local** registries need no network auth.
+
+## Install the CLI
+
+```bash
+npx skissue --help
+```
+
+Or install globally:
+
+```bash
+npm install -g skissue
+skissue --help
+```
+
+With no arguments, **`npx skissue`** runs interactive **setup** (`.skill-issue/config.yaml`) if needed, then opens the **manage** menu to install or remove skills.
+
+### From source
+
+```bash
+git clone https://github.com/midyan/skill-issue.git
+cd skill-issue
+npm install
+npm run build
+node dist/entry.js --help
+```
+
+**Automated publish (CI):**
+
+1. **Pull requests:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs **`npm run verify`** (TypeScript, ESLint, Prettier, tests, harness, build).
+2. **Push to `main`:** Same **verify** runs unless the commit message contains **`[skip ci]`** (used by the automated version bump so the full suite does not run twice for that commit).
+3. When **CI succeeds** after a push to **`main`**, [`.github/workflows/version-and-release.yml`](.github/workflows/version-and-release.yml) bumps the **patch** version, commits to **`main`** with **`[skip ci]`**, then creates a **GitHub Release** and tag **`v<version>`**. That tag triggers [`.github/workflows/publish.yml`](.github/workflows/publish.yml) to **`npm publish --provenance --access public`** to the public npm registry.
+
+**Branch protection:** `GITHUB_TOKEN` must be allowed to **push to `main`** and create releases (or use a PAT with `contents: write` stored as a secret). If publish fails after the tag exists, **re-run** the publish workflow or use **workflow dispatch** with the tag (e.g. `v0.1.0`).
+
+## Quick start
+
+### Consumer project + GitHub registry
+
+```bash
+cd your-consumer-repo
+skissue init   # choose "GitHub" and enter owner/repo
+skissue install skill-issue
+```
+
+### Local skill-registry checkout
+
+Point **`registry.path`** at a clone of **skill-registry** (or another repo whose root has **`registry.json`** and **`registry/`**):
+
+```bash
+cd /path/to/your-consumer
+npm run dev -- init    # choose "Local directory", path ../skill-registry
+skissue install skill-issue
+```
+
+`registry.path` is **relative to the consumer project root** (where `.skill-issue/` lives). The local registry must be a **git** checkout so `HEAD` can be stored in the lockfile.
+
+`init` writes `.skill-issue/config.yaml` (either **`registry.path`** or **`registry.owner` / `registry.repo`**, optional **`registry.useSsh`**, branch, and skills root). `install` resolves the path from **`registry.json`** (or **`registry/<id>`** by convention), copies into **`skillsRoot/<id>/`**, and updates **`.skill-issue/lock.json`**.
+
+**Remote transport (auto):** if **`registry.useSsh`** is omitted, the CLI uses **SSH** (`git@github.com:…`) when **`GITHUB_TOKEN` / `GH_TOKEN` are unset** (typical laptop with GitHub SSH keys), and **HTTPS with a token** when a token is set (CI). Set **`registry.useSsh: true`** or **`false`** to force SSH or HTTPS.
+
+## Environment
+
+| Variable       | Purpose                                                                             |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `GITHUB_TOKEN` | HTTPS auth when the resolved transport is HTTPS (e.g. CI, or auto when this is set) |
+| `GH_TOKEN`     | Same as above if `GITHUB_TOKEN` is unset                                            |
+
+Do not put tokens in `config.yaml`; keep them in the environment or credential helper.
+
+## Registry layout (in the registry repo)
+
+- **`registry.json`** at the **repository root** maps skill ids to paths (typically under **`registry/`**):
+
+```json
+{
+  "skills": {
+    "my-skill": "registry/my-skill"
+  }
+}
+```
+
+- If `registry.json` is missing or does not list an id, the convention **`registry/<id>/`** is used.
+
+## Commands
+
+| Command                  | Description                                       |
+| ------------------------ | ------------------------------------------------- |
+| `skissue init`           | Create config interactively                       |
+| `skissue install <id>`   | Install skill at registry branch tip; update lock |
+| `skissue uninstall <id>` | Remove install dir and lock entry                 |
+| `skissue list`           | Show installed ids and lock metadata              |
+| `skissue manage`         | Interactive menu to install or uninstall skills   |
+| `skissue outdated`       | Compare locked commit vs current branch path diff |
+| `skissue update [id]`    | Re-install from registry                          |
+| `skissue doctor`         | Check Node, config, `git ls-remote`               |
+
+`manage` is also available as `skissue browse`.
+
+### Interactive
+
+After `init`, run `skissue manage` (or `browse`) to see registry skills vs installed skills and batch install or uninstall with prompts. Non-interactive `install` / `uninstall` remain for scripts.
+
+## Development
+
+```bash
+npm install   # installs deps and runs `prepare` — enables Husky git hooks
+npm run verify
+```
+
+**`npm run verify`** runs TypeScript (`tsc --noEmit`), ESLint, Prettier check, Vitest, **`npm run check:all`** ( **`harness/runner.ts`** — each **`harness/<id>/hard/index.ts`** without **`hard/.no-auto-run`** ), then **`npm run build`**. The same pipeline runs on **`git commit`** via **`.husky/pre-commit`** (skip with **`git commit --no-verify`** if needed). See [harness/SKILL.md](harness/SKILL.md), [harness/repo-verify/SKILL.md](harness/repo-verify/SKILL.md), and [docs/HARNESS.md](docs/HARNESS.md).