@dk/hipp 0.1.34 → 0.1.36

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
@@ -70,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
 
@@ -90,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,
@@ -111,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 `--`:
 
@@ -126,20 +140,21 @@ npx @dk/hipp -- --access public --tag beta
 HIPP provides out-of-band verification to prove package integrity:
 
 ```bash
-npx @dk/hipp verify                       # auto-detect: local hipp repo → published version, else @dk/hipp
-npx @dk/hipp verify --self                # always verifies @dk/hipp itself
-npx @dk/hipp verify @scope/package         # verifies latest of a package
-npx @dk/hipp verify @scope/package@1.0.0   # verifies specific version
+npx @dk/hipp --verify                       # auto-detect: local hipp repo → published version, else @dk/hipp
+npx @dk/hipp --verify --self                # always verifies @dk/hipp itself
+npx @dk/hipp --verify @scope/package         # verifies latest of a package
+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",
@@ -156,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
@@ -165,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
@@ -187,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.
@@ -240,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.
@@ -258,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.34
+npx @dk/hipp --verify @dk/hipp@0.1.36
 ```
 
 ```json
 {
   "origin": "git@github.com:dmytri/hipp.git",
-  "tag": "v0.1.34",
-  "revision": "55f9f1d7305d9d88eb46a3d8f619bca05979edf4",
-  "hash": "4c9d71d9d766442078d3ca2ea97cb36038567883c4ffbaa20ba57b38c75edd20",
-  "signature": "TUB/PMMp7wLSgqlkw2hkf2b5YdvjbZ852MdyQBn/uhE4k1VntUlJOuK5L6I6aX1Aalkteqw7zKUhOWyCyfq4Bg==",
+  "tag": "v0.1.36",
+  "revision": "e3190c19274fd1dcf9c9f8d4f3a0af842214e4b7",
+  "hash": "af45dd66df7b54705c7c0c2a5e3bd24222727bc34668e2d89c8079175cdd1df4",
+  "signature": "hFkmTxDeTNHOhvvVlySj2Amg5Wq2vuFR1fJzBU0d4Th5ixMvkbpdLcYiHu719sZVAWsUycnu56pH2rXZCvN+BA==",
   "name": "Dmytri Kleiner",
   "email": "dev@dmytri.to",
   "npm": "11.12.1",
   "node": "v25.8.2",
   "git": "git version 2.47.3",
-  "hipp": "0.1.34"
+  "hipp": "0.1.36"
 }
 ```

package/hipp.js

@@ -564,7 +564,7 @@ async function runVerify(packageSpec) {
         stagedReadme = stagedReadme.trimEnd() + '\n\n## Verify\n\n' +
           'Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):\n\n' +
           '```bash\n' +
-          `npx @dk/hipp verify ${pkgName}@${tagVersion}\n` +
+          `npx @dk/hipp --verify ${pkgName}@${tagVersion}\n` +
           '```\n\n' +
           '```json\n' + JSON.stringify(manifest, null, 2) + '\n```\n';
         fs.writeFileSync(stagedReadmePath, stagedReadme);
@@ -746,7 +746,7 @@ async function run() {
     stagedReadme = stagedReadme.trimEnd() + '\n\n## Verify\n\n' +
       'Verify this package with [@dk/hipp](https://www.npmjs.com/package/@dk/hipp):\n\n' +
       '```bash\n' +
-      `npx @dk/hipp verify ${pkg.name}@${version}\n` +
+      `npx @dk/hipp --verify ${pkg.name}@${version}\n` +
       '```\n\n' +
       '```json\n' + JSON.stringify(manifestJson, null, 2) + '\n```\n';
     fs.writeFileSync(stagedReadmePath, stagedReadme);
@@ -787,8 +787,8 @@ async function run() {
   }
 }
 
-const isVerify = process.argv.includes('verify');
-const verifyIndex = process.argv.indexOf('verify');
+const isVerify = process.argv.includes('--verify');
+const verifyIndex = process.argv.indexOf('--verify');
 const packageSpec = verifyIndex !== -1 ? process.argv[verifyIndex + 1] : null;
 
 if (isVerify) {
@@ -817,8 +817,8 @@ if (isVerify) {
 
 Usage:
   npx hipp [options] [-- npm-options]
-  npx hipp verify [@package[@version]]
-  npx hipp verify --self
+  npx hipp --verify [@package[@version]]
+  npx hipp --verify --self
 
   Without arguments: in a hipp repo (package.json version 0.0.0 or matching
   a semver tag on HEAD), verifies the published package at that version.

package/package.json

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