From 6fff5f91a17e4e201240e41c06726c7a96791f73 Mon Sep 17 00:00:00 2001
From: cyrilxc <cyrilxchan@gmail.com>
Date: Mon, 30 Mar 2026 21:21:53 +0800
Subject: [PATCH] chore(dev): add local pack and refresh workflow

---
 docs/local-development.md | 37 +++++++++++++++++++++++++++++++++++++
 package.json              |  4 ++++
 2 files changed, 41 insertions(+)
 create mode 100644 docs/local-development.md

diff --git a/docs/local-development.md b/docs/local-development.md
new file mode 100644
index 00000000..eba9a412
--- /dev/null
+++ b/docs/local-development.md
@@ -0,0 +1,37 @@
+# Local Development
+
+## Environment
+- Node.js `>=18` is required; the current local setup uses Node `22.x`.
+- Install dependencies with `npm install`.
+- Runtime configuration is loaded from `.env`. Keep secrets and machine-specific values out of git.
+
+## Common Workflows
+- `npm run build`: compile TypeScript into `dist/`.
+- `npm run start`: run from source with `ts-node`.
+- `npm run start:built`: run the compiled build.
+- `node dist/bin/cli.js start`: validate the packaged CLI path directly.
+- `npm test`: run the main Jest suite.
+
+## Local Packaging
+Keep the tracked `package.json` version unchanged. For personal builds, use a local-only override such as `package.local.json` and exclude it via `.git/info/exclude`, not the tracked `.gitignore`.
+
+Current local packaging pattern:
+- public package: `lazy-gravity@0.5.5`
+- local package: `lazy-gravity-local@0.5.5-local.YYMMDDHHMM`
+
+Local version rule:
+- Keep the public version from tracked `package.json` unchanged.
+- Update `package.local.json` for each local build/install.
+- Use a traceable timestamp suffix in local builds, for example `0.5.5-local.2603151617`.
+- The suffix format is `YYMMDDHHMM` in your local timezone so every build can be traced back to its packaging time.
+
+Use a staged package build when you need a second global install:
+1. Build the repo with `npm run build`.
+2. Merge `package.json` with `package.local.json` into a temporary staging directory.
+3. Pack or install that staged directory as `lazy-gravity-local`.
+
+Recommended command:
+- `npm run local:pack`
+- This updates `package.local.json` with a fresh `0.5.5-local.YYMMDDHHMM` style version, rebuilds `dist/`, stages the local package metadata, and writes the `.tgz` into the repo root.
+
+This keeps contributor-facing metadata clean while allowing a separate local binary for development.
diff --git a/package.json b/package.json
index 1e83c4ce..7f781005 100644
--- a/package.json
+++ b/package.json
@@ -23,6 +23,10 @@
     "test:integration": "jest tests/e2e.bot.test.ts",
     "test:watch": "jest --watch",
     "build": "tsc",
+    "local:pack": "node scripts/pack-local.js",
+    "refresh": "bash scripts/rebuild-reinstall-restart.sh local",
+    "refresh:local": "bash scripts/rebuild-reinstall-restart.sh local",
+    "refresh:main": "bash scripts/rebuild-reinstall-restart.sh main",
     "start": "ts-node src/bin/cli.ts",
     "start:built": "node dist/bin/cli.js",
     "dev": "ts-node-dev --respawn src/bin/cli.ts",