json5-manifest-sync 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.1.4] - 2026-05-05
+
+### Changed
+
+- Renamed the CLI option for suppressing generated blank `//` spacer comments to clearer `--remove-empty-comments` and `--remove-blank-comments` forms.
+- Kept legacy `--no-empty-comment` and `--no-empty-comments` aliases working for compatibility.
+
+## [0.1.3] - 2026-02-27
+
+### Added
+
+- Published `json5-manifest-sync` to the npm registry for direct install and global CLI usage.
+- Added npm-first installation guidance in the README, including optional global install instructions.
+
+### Changed
+
+- Updated README examples to use npm semver dependency references instead of GitHub-only install URLs.
+- Kept GitHub install instructions as an alternative path for unreleased branch/tag consumption.
+
 ## [0.1.2] - 2026-02-25
 
 ### Fixed

package/README.md

@@ -1,11 +1,11 @@
 # json5-manifest-sync
 
-Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers.
+Keep a documented `package.json5` in sync with the real `package.json` used by Node and package managers, including `version` updates.
 
 ## Quick Start
 
 ```bash
-npm install github:BBaysinger/json5-manifest-sync#v0.1.3
+npm install --save-dev json5-manifest-sync
 ```
 
 Add a script in your project's `package.json`:
@@ -41,37 +41,49 @@ This tool solves that gap by letting you maintain both:
 - `package.json5` as the human-documented companion file
 
 Then it synchronizes `package.json5` from `package.json` while preserving mapped `//` comments where possible.
+When values like `version`, `scripts`, or dependency versions change in `package.json`, those updates are propagated into `package.json5`.
 
 ## What it does
 
 - Finds `package.json` files recursively (excluding `node_modules`)
 - Skips paths ignored by your root `.gitignore`
-- For each matching `package.json5`, rewrites values from canonical `package.json`
+- For each matching `package.json5`, rewrites values from canonical `package.json` (including `version`, scripts, dependencies, and other manifest fields)
 - Preserves/migrates mapped `//` comments for keys and supported array items
+- Inserts a blank `//` comment line before keys with no mapped comment (enabled by default)
 - Writes stable JSON5 formatting with trailing commas for cleaner diffs
 
+### Current limitations
+
+- Per-item comment preservation is most reliable for arrays of strings.
+- Arrays of objects or numbers still serialize correctly, but item-level comments may be dropped or replaced by an empty `//` spacer on sync.
+- If you prefer to avoid regenerated blank spacer comments in those cases, run the CLI with `--remove-empty-comments`.
+
 Repository: https://github.com/BBaysinger/json5-manifest-sync
 
 ## Author
 
 Bradley Baysinger ([@BBaysinger](https://github.com/BBaysinger))
 
-## Install from GitHub
+## Install from npm (recommended)
 
-Install from a tag (recommended):
+```bash
+npm install --save-dev json5-manifest-sync
+```
+
+Global install (optional):
 
 ```bash
-npm install github:BBaysinger/json5-manifest-sync#v0.1.3
+npm install -g json5-manifest-sync
 ```
 
-Or from a branch during iteration:
+## Install from GitHub (alternative)
+
+Use this if you want an unreleased branch or tag:
 
 ```bash
 npm install github:BBaysinger/json5-manifest-sync#main
 ```
 
-Because this repo defines a `prepare` script, npm will build TypeScript during git-based install.
-
 ## Use in a project
 
 Add a script in your consuming project's `package.json`:
@@ -113,10 +125,14 @@ For the current full output style, see this repo's live example: [`package.json5
 
 ### Options
 
-- `--no-empty-comment` or `--no-empty-comments`
+By default, the tool inserts an empty `//` line before keys that do not already have a mapped comment. Disable that behavior with one of the following:
+
+- `--remove-empty-comments` or `--remove-blank-comments`
 - `--empty-comment=false`
 - env var: `SYNC_JSON5_ADD_EMPTY_COMMENT=false`
 
+Legacy aliases `--no-empty-comment` and `--no-empty-comments` are still accepted for compatibility.
+
 ### Formatting note
 
 Recommended: exclude `package.json5` from Prettier (for example via `.prettierignore`).
@@ -126,12 +142,22 @@ Prettier's JSON5 formatter can remove quotes from valid keys, which makes `packa
 > [!NOTE]
 > It would be nice if Prettier provided an option to preserve quoted keys in JSON5.
 
+### AI assist tip
+
+After running `sync:json5`, you can ask an AI coding assistant to fill placeholder comment lines.
+
+If you use this repo's `precommit` workflow, it warns when `package.json5` still contains blank `//` placeholder comments. Suppress just that warning for a given run with `npm run precommit -- --suppress-blank-comment-warning`.
+
+Example prompt:
+
+> "Complete empty `//` comment lines in `package.json5` with concise, field-specific comments."
+
 ## Example dependency block in consumer
 
 ```json
 {
   "dependencies": {
-    "json5-manifest-sync": "github:BBaysinger/json5-manifest-sync#v0.1.3"
+    "json5-manifest-sync": "^0.1.3"
   }
 }
 ```

package/dist/json5-manifest-sync.d.ts

@@ -36,8 +36,9 @@ export type SyncOptions = {
      *   //
      *   "type": "module",
      *
-     * Defaults to true. Can be disabled via CLI flag `--no-empty-comment` or the
-     * environment variable `SYNC_JSON5_ADD_EMPTY_COMMENT=false`.
+     * Defaults to true. Can be disabled via CLI flags like
+     * `--remove-empty-comments` or the environment variable
+     * `SYNC_JSON5_ADD_EMPTY_COMMENT=false`.
      */
     addEmptyCommentIfMissing?: boolean;
 };

package/dist/json5-manifest-sync.js

@@ -336,9 +336,14 @@ export function runCli(args = process.argv.slice(2)) {
         process.env.SYNC_JSON5_ADD_EMPTY_COMMENT.toLowerCase() === "false") {
         addEmptyCommentIfMissing = false;
     }
-    // CLI toggles: --no-empty-comment, --empty-comment=false
+    // CLI toggles: --remove-empty-comments, --remove-blank-comments
     for (const arg of args) {
-        if (arg === "--no-empty-comment" || arg === "--no-empty-comments") {
+        if (arg === "--remove-empty-comment" ||
+            arg === "--remove-empty-comments" ||
+            arg === "--remove-blank-comment" ||
+            arg === "--remove-blank-comments" ||
+            arg === "--no-empty-comment" ||
+            arg === "--no-empty-comments") {
             addEmptyCommentIfMissing = false;
         }
         else if (arg.startsWith("--empty-comment=")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json5-manifest-sync",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Sync package.json5 files from canonical package.json while preserving key comments.",
   "author": {
     "name": "Bradley Baysinger",
@@ -16,7 +16,7 @@
     }
   },
   "bin": {
-    "json5-manifest-sync": "./dist/json5-manifest-sync.js"
+    "json5-manifest-sync": "dist/json5-manifest-sync.js"
   },
   "files": [
     "dist",
@@ -25,8 +25,11 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "sync:json5": "node ./dist/json5-manifest-sync.js",
+    "warn:blank-comments": "node ./scripts/warn-blank-comments.mjs",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
+    "precommit": "node ./scripts/precommit.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepare": "npm run build"
@@ -35,13 +38,13 @@
     "node": ">=18"
   },
   "dependencies": {
-    "glob": "^11.0.1",
-    "ignore": "^7.0.4"
+    "glob": "^13.0.6",
+    "ignore": "^7.0.5"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
-    "prettier": "^3.8.1",
-    "typescript": "^5.8.2",
-    "vitest": "^2.1.9"
+    "@types/node": "^25.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }