@dk/hipp 0.1.33 → 0.1.35

package/README.md

@@ -6,6 +6,16 @@ By Dmytri Kleiner <dev@dmytri.to>
 commits and merge conflicts by treating Git Tags as the single source of truth.
 Your `package.json` version stays at `0.0.0` (or matches your latest tag).
 
+## TL;DR
+
+```bash
+git tag v1.0.0
+git push origin main --tags
+npx @dk/hipp
+```
+
+Your package is published with version `1.0.0`. No version-bump commits. No merge conflicts.
+
 ---
 
 ## The Problem
@@ -13,11 +23,11 @@ Your `package.json` version stays at `0.0.0` (or matches your latest tag).
 Traditional NPM versioning requires storing the "Version of Truth" in `package.json`.
 This creates a **State Conflict**:
 
-- `npm version` and `git tag` are two distinct, non-atomic actions
-- If you tag a commit but forget to update the JSON (or vice-versa), your
+- 🔄 `npm version` and `git tag` are two distinct, non-atomic actions
+- 🤷 If you tag a commit but forget to update the JSON (or vice-versa), your
   registry package and Git history diverge
-- Every release requires a "chore: bump version" commit
-- When multiple branches are developed simultaneously, these trivial changes
+- 🗑️ Every release requires a "chore: bump version" commit
+- 😫 When multiple branches are developed simultaneously, these trivial changes
   cause constant merge conflicts
 
 ## The Solution
@@ -25,7 +35,8 @@ This creates a **State Conflict**:
 **HIPP makes Git tags the source of truth** - the version is always extracted
 from the tag, not `package.json`. You can leave `package.json` at `0.0.0` (HIPP
 rewrites it during publish) or keep it in sync with your tag (HIPP verifies the
-match).
+match). The published package always has the correct semver from your git tag —
+downstream consumers see normal versions and `npm install` works as expected.
 
 ---
 
@@ -69,15 +80,15 @@ Pass npm options via `--`:
 npx @dk/hipp -- --access public --tag beta
 ```
 
-HIPP will:
+### What Happens When You Run HIPP
 
-1. **Key Generation**: Generate Ed25519 signing keys if needed (`hipp.priv`, `hipp.pub`)
-2. **Verify**: Ensure `package.json` version is `0.0.0` or matches the git tag
-3. **Clean Check**: Ensure your git status is clean
-4. **Validate**: Extract and verify the latest tag against Semver rules
-5. **Sign**: Create a cryptographic manifest of your package content
-6. **Publish**: Publish to npm from a staging directory (never mutating your source)
-7. **Confirm**: Ask for confirmation before ignition (skip with `-y`)
+1. **Key Generation** - Generate Ed25519 signing keys if needed (`hipp.priv`, `hipp.pub`)
+2. **Verify** - Ensure `package.json` version is `0.0.0` or matches the git tag
+3. **Clean Check** - Ensure your git status is clean
+4. **Validate** - Extract and verify the latest tag against Semver rules
+5. **Sign** - Create a cryptographic manifest of your package content
+6. **Publish** - Publish to npm from a staging directory (never mutating your source)
+7. **Confirm** - Ask for confirmation before ignition (skip with `-y`)
 
 ### Signing Keys
 
@@ -89,15 +100,19 @@ On first run, HIPP generates an Ed25519 keypair:
 
 The private key holder can sign packages. The public key verifies signatures.
 
-**Key rotation**: Delete `hipp.pub` and run HIPP again. A new keypair will be
+#### Key Rotation
+
+Delete `hipp.pub` and run HIPP again. A new keypair will be
 generated and committed automatically. Verification uses the public key from
 the specific git revision at the tag, so previous packages remain verifiable
 with their original keys.
 
-**Multiple publishers**: Each developer can use their own private key. Delete
-`hipp.pub`, run HIPP, and a new keypair will be generated for that revision.
+#### Multiple Publishers
 
-### Why This Works
+Each developer can use their own private key. Delete `hipp.pub`, run HIPP, and
+a new keypair will be generated for that revision.
+
+#### Why This Works
 
 The public key in `hipp.pub` is committed to git at the specific revision of
 each release. Verification always uses the key from that historical revision,
@@ -110,7 +125,7 @@ not a current one. This means:
 
 ### Options
 
-* `-y, --yes`: Skip the confirmation prompt (ideal for CI/CD pipelines).
+- `-y, --yes` - Skip the confirmation prompt (ideal for CI/CD pipelines)
 
 To pass additional flags to npm publish (like access or a custom registry), use `--`:
 
@@ -133,12 +148,13 @@ npx @dk/hipp verify @scope/package@1.0.0   # verifies specific version
 
 ### How Verification Works
 
-**Step 1: Get manifest from npm**
+#### Step 1: Get Manifest from npm
 
 1. Fetch the package tarball from npm registry
 2. Extract the README and parse the JSON manifest appended to it
 
 The manifest contains:
+
 ```json
 {
   "origin": "git@github.com:dk/your-package.git",
@@ -155,7 +171,7 @@ The manifest contains:
 }
 ```
 
-**Step 2: Clone git and verify**
+#### Step 2: Clone Git and Verify
 
 3. Clone the repository at the tagged commit (using origin/tag from manifest)
 4. Verify the cloned commit hash matches the `revision` field in manifest
@@ -164,13 +180,13 @@ The manifest contains:
 7. Compute SHA256 hash of the clean tarball
 8. Compare with the `hash` field from the npm manifest
 
-**Step 3: Verify signature**
+#### Step 3: Verify Signature
 
 9. Read `hipp.pub` from the cloned repository
 10. Verify the signature was created by signing:
     `hash + "\n" + origin + "\n" + tag + "\n" + revision + "\n" + name + "\n" + email`
 
-**Step 4: Rebuild verification**
+#### Step 4: Rebuild Verification
 
 11. Append the manifest to the staged README
 12. Update the staged `package.json` version to match the tag
@@ -186,15 +202,15 @@ The manifest contains:
 
 ### What Verification Guarantees
 
-- **Integrity**: The code in npm exactly matches git at the tagged commit
-- **Authenticity**: The package was published by the holder of the private key
-- **Reproducibility**: The npm tarball is byte-for-byte identical to a git rebuild
+- **Integrity** - The code in npm exactly matches git at the tagged commit
+- **Authenticity** - The package was published by the holder of the private key
+- **Reproducibility** - The npm tarball is byte-for-byte identical to a git rebuild
 
 ### What Verification Does NOT Guarantee
 
-- **Code is safe or bug-free**: Malicious or buggy code can be signed
-- **Publisher is trustworthy**: The key holder could sign bad code intentionally
-- **Name/email is accurate**: These are read from local `git config` and could be set to anything
+- **Code is safe or bug-free** - Malicious or buggy code can be signed
+- **Publisher is trustworthy** - The key holder could sign bad code intentionally
+- **Name/email is accurate** - These are read from local `git config` and could be set to anything
 
 Verification proves that npm matches git - it says nothing about whether that
 code is correct or safe.
@@ -239,7 +255,7 @@ HIPP enforces strict integrity rules when publishing:
 
 ## License
 
-**0BSD** (BSD Zero Clause License)  By Dmytri Kleiner <dev@dmytri.to>
+**0BSD** (BSD Zero Clause License) By Dmytri Kleiner <dev@dmytri.to>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted.
@@ -257,21 +273,21 @@ PERFORMANCE OF THIS SOFTWARE.
 Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):
 
 ```bash
-npx @dk/hipp verify @dk/hipp@0.1.33
+npx @dk/hipp verify @dk/hipp@0.1.35
 ```
 
 ```json
 {
   "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.33",
-  "revision": "9374cd1fb9e8046983abaebd21f4812bcc80ef5a",
-  "hash": "bb54c711b30be14366f26749253801f8a9ac13efaa774d2aa5f6044f5f9980bb",
-  "signature": "U7oLJCB+Efv5tWJ9Zy7kp4saa+i1K7Z7N8+vW6e0l0AZahQpTPhZiM1ZMC5MM5g8rxnjt/NxwwCUEacVoDiPCg==",
+  "tag": "v0.1.35",
+  "revision": "1867eb114a7c672dd23da33d6b6b4375077faf4d",
+  "hash": "8a48b6de8cdfd06b93177720f9701b77dc96263b20c10902a8b5780f5941489a",
+  "signature": "R5wbqWXbsV4269e78lDuN92FyWkWk0L4jSsQgLQSVc1/vOis/IKWA+UFMxdIKOfThczLLNm98YDpcu4QEITNBA==",
   "name": "Dmytri Kleiner",
   "email": "dev@dmytri.to",
   "npm": "11.12.1",
   "node": "v25.8.2",
   "git": "git version 2.47.3",
-  "hipp": "0.1.33"
+  "hipp": "0.1.35"
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dk/hipp",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "High Integrity Package Publisher",
   "main": "hipp.js",
   "bin": {