hyper-pm 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -11
- package/dist/index.cjs +1530 -886
- package/dist/main.cjs +1530 -886
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -40,6 +40,14 @@ These apply before any subcommand (for example `hyper-pm --format text epic read
|
|
|
40
40
|
|
|
41
41
|
## Commands
|
|
42
42
|
|
|
43
|
+
### Work item display numbers
|
|
44
|
+
|
|
45
|
+
Each epic, story, and ticket has a durable ULID `id` plus a per-type **`number`**: a small positive integer (separate counters for epics, stories, and tickets). List JSON includes `number` on each row; full `read` JSON includes it on the record.
|
|
46
|
+
|
|
47
|
+
Any CLI flag that accepts a work item **`--id`** (or a parent like `--epic`, `--story`, or ticket list filters that take ids) also accepts that item’s **`number`** when it is written as an all-digit token (for example `ticket read 3` after you confirm ticket `3` in `ticket read` list output). Resolution tries the ULID/id string first, then a unique numeric match. If two items share the same `number` after a bad merge, numeric lookup is ambiguous and the command fails until the JSONL conflict is fixed.
|
|
48
|
+
|
|
49
|
+
Parallel offline edits can still assign the same next `number` on different branches; resolving that is the same class of problem as other JSONL merge conflicts.
|
|
50
|
+
|
|
43
51
|
### `init`
|
|
44
52
|
|
|
45
53
|
Create or adopt the orphan data branch and write `.hyper-pm/config.json`.
|
|
@@ -74,9 +82,9 @@ Uses global options only (no subcommand-specific flags).
|
|
|
74
82
|
| `work` | Start work in the primary clone | **Required:** `--id <id>`. **Optional:** `--branch <name>` (default `hyper-pm/<id>`; if that local branch already exists, appends `-2`, `-3`, … to the **whole** preferred name, e.g. `hyper-pm/ticket-1` → `hyper-pm/ticket-1-2`), `--from <ref>` (fork point; default: `refs/remotes/<remote>/HEAD` when present, else `main`, `master`, or `HEAD`). Creates and checks out the new branch, sets the ticket to `in_progress`, and appends the branch to linked branches. Rejects tickets in `done` or `cancelled`. Success JSON includes `branch` and, when a suffix was applied, `branchPreferred`. |
|
|
75
83
|
| `comment` | Append a ticket comment (local event log) | **Required:** `--id <id>`, `--body <text>` (non-empty after trim). Appends `TicketCommentAdded`; `ticket read --id` includes a `comments` array. |
|
|
76
84
|
| `delete` | Soft-delete a ticket | **Required:** `--id <id>` |
|
|
77
|
-
| `import-github` | Import GitHub issues as local tickets | **Optional:** `--dry-run` (list candidates and skips, no JSONL writes), `--story <id>` (attach every imported ticket to this story; must exist), `--state <s>` (`open`, `closed`, or `all`; default `all` — passed to GitHub’s issues list), `--issue <n>` (repeatable or comma-separated; only consider those numbers). Requires `issueMapping: "ticket"` in config. Skips pull requests, issues already linked to a ticket, and issues whose body contains a non-empty `hyper_pm_id` in the JSON fence (live ticket, deleted ticket, or broken reference). Maps title (strips `[hyper-pm]` prefix), description before the first fenced block, closed state → `done`, first assignee, non-reserved labels, and known planning fields from the fence. After a real import, run
|
|
85
|
+
| `import-github` | Import GitHub issues as local tickets | **Optional:** `--dry-run` (list candidates and skips, no JSONL writes), `--story <id>` (attach every imported ticket to this story; must exist), `--state <s>` (`open`, `closed`, or `all`; default `all` — passed to GitHub’s issues list), `--issue <n>` (repeatable or comma-separated; only consider those numbers). Requires `issueMapping: "ticket"` in config. Skips pull requests, issues already linked to a ticket, and issues whose body contains a non-empty `hyper_pm_id` in the JSON fence (live ticket, deleted ticket, or broken reference). Maps title (strips `[hyper-pm]` prefix), description before the first fenced block, closed state → `done`, first assignee, non-reserved labels, and known planning fields from the fence. After a real import, run **`sync --with-github`** once so outbound sync rewrites each GitHub body with the hyper-pm fence. |
|
|
78
86
|
|
|
79
|
-
Tickets store at most one assignee (GitHub login).
|
|
87
|
+
Tickets store at most one assignee (GitHub login). When you run **`sync --with-github`**, outbound updates set that user as the issue’s only assignee (extra assignees on the issue may be removed), and inbound reads the first assignee from the API when the issue has several. Outbound **creates** GitHub issues only for tickets that have a valid epic+story chain; unlinked tickets are skipped until you set `--story`. Tickets that **already** have a linked GitHub issue are still **updated** when unlinked (issue body drops parent ids until you link again).
|
|
80
88
|
|
|
81
89
|
### `repo`
|
|
82
90
|
|
|
@@ -89,20 +97,24 @@ Read-only helpers against the **checked-out repository** (not the hyper-pm data
|
|
|
89
97
|
|
|
90
98
|
### `sync`
|
|
91
99
|
|
|
92
|
-
|
|
100
|
+
**Default (no flags):** reconciles the **`hyper-pm-data`** branch over git: `git fetch` of the configured branch on `remote`, `git merge` of `refs/remotes/<remote>/<dataBranch>` when that ref exists (bounded **push retries** on likely non-fast-forward races), then **`git push`**. Does **not** call the GitHub Issues API and does **not** require `GITHUB_TOKEN` or `gh`. Runs even when `sync` is **`off`** in config. JSON includes `gitDataOnly: true` plus **`dataBranchFetch`**, **`dataBranchMerge`**, **`dataBranchPush`**, optional **`dataBranchPushDetail`**, and **`pushAttempts`**. A merge conflict aborts the merge and exits with a user error. Pass **`--skip-push`** to fetch/merge without pushing.
|
|
101
|
+
|
|
102
|
+
**`--with-github`:** additionally runs **GitHub Issues** sync when `sync` is **`outbound`** or **`full`** in config (not when `sync` is **`off`**). **Outbound** sets issue `labels` to `hyper-pm`, `ticket`, plus each ticket label (GitHub’s 50-character label limit applies), and embeds ticket planning in the fenced JSON after the description. **Inbound** (`sync: full`) compares the issue’s non-reserved labels and that fence to the projection and appends `GithubInboundUpdate` when anything differs. With `sync: full`, after inbound it may load linked PR timelines for **`in_progress`** tickets with `Refs` / `Closes` / `Fixes #<n>` in the body (`GithubPrActivity`). Requires **`GITHUB_TOKEN`** **or** `gh auth login`. After GitHub API work, **`hyper-pm` commits on the data branch** using `git -c user.name=… -c user.email=… commit` (same identity resolution as mutations). JSON then includes `githubSync: true` plus **`dataBranchPush`** / optional **`dataBranchPushDetail`** (same push semantics as the default path).
|
|
93
103
|
|
|
94
|
-
|
|
104
|
+
**`--skip-network`:** skips **all** sync network work (no git fetch/merge/push, no GitHub). JSON `{ "ok": true, "skipped": true }`. The legacy spelling **`--no-github`** is still accepted (it is normalized to **`--skip-network`** before parsing).
|
|
95
105
|
|
|
96
|
-
|
|
106
|
+
**`--git-data`:** legacy no-op; default behavior is already git-only. If passed, JSON may include `legacyGitDataFlag: true`.
|
|
97
107
|
|
|
98
|
-
|
|
108
|
+
For any path that pushes, a missing remote or push error **does not fail the command** for exit code: JSON still has `"ok":true` with **`dataBranchPush`** set to `pushed`, `skipped_no_remote`, `failed`, or (with **`--skip-push`**) `skipped_cli`. Push failures are also written to stderr as a single-line hint.
|
|
99
109
|
|
|
100
|
-
| Option
|
|
101
|
-
|
|
|
102
|
-
| `--
|
|
103
|
-
| `--skip-
|
|
110
|
+
| Option | Description | Default |
|
|
111
|
+
| ---------------- | ------------------------------------------------------------------------ | --------------------------- |
|
|
112
|
+
| `--with-github` | Also run GitHub Issues sync (needs auth; `sync` not `off`) | `false` |
|
|
113
|
+
| `--skip-network` | Skip all sync network operations (git and GitHub); legacy: `--no-github` | `false` |
|
|
114
|
+
| `--git-data` | Legacy; same as default | `false` |
|
|
115
|
+
| `--skip-push` | Skip `git push` of the data branch after sync | `false` (push is attempted) |
|
|
104
116
|
|
|
105
|
-
|
|
117
|
+
For a successful push you need a configured remote and credentials that allow `git push` to that remote.
|
|
106
118
|
|
|
107
119
|
### `audit`
|
|
108
120
|
|