@hkonda/loco-translate 1.0.3 → 1.0.4

package/README.md

@@ -349,3 +349,65 @@ flowchart TB
 | Build Tool | Vite |
 | AI | BlueHive API |
 | Deployment | systemd + deploy.sh |
+
+---
+
+## Publishing an NPM Update
+
+Use this checklist whenever you add new features or fixes and want to release a new version.
+
+### 1. Make your changes
+
+Work on `main` or a feature branch as normal. Run `npm run dev` to develop locally.
+
+### 2. Bump the version
+
+Edit `package.json` at the root — increment `"version"` following [semver](https://semver.org/):
+
+```
+patch (1.0.3 → 1.0.4) — bug fixes, small tweaks
+minor (1.0.3 → 1.1.0) — new backwards-compatible features
+major (1.0.3 → 2.0.0) — breaking changes
+```
+
+### 3. Build the package
+
+```bash
+node scripts/build-npm.js
+```
+
+This compiles the TypeScript server, builds the Svelte dashboard (with the correct `/dashboard/` base path), builds the CDN client bundles, and assembles everything into `npm-package/`.
+
+### 4. Publish
+
+```bash
+cd npm-package
+echo '//registry.npmjs.org/:_authToken=<your-npm-token>' > .npmrc
+npm publish --access public
+rm .npmrc
+```
+
+Get a token at [npmjs.com → Access Tokens](https://www.npmjs.com/settings/~/tokens) — use a **Classic Automation** token (bypasses 2FA).
+
+### 5. Verify
+
+```bash
+npm install -g @hkonda/loco-translate@<new-version>
+loco
+```
+
+Open `http://localhost:6101/dashboard/` to confirm everything loads.
+
+---
+
+### What the build script does
+
+| Step | Command | Output |
+|---|---|---|
+| Compile server | `tsc -p tsconfig.server.json` | `dist-server/` |
+| Build dashboard | `vite build` (with `LOCO_VITE_BASE=/dashboard/`) | `dist/` |
+| Build CDN (minified) | `vite build` in `client/` | `public/loco.min.js` |
+| Build CDN (unminified) | `cross-env LOCO_UNMINIFIED=1 vite build` in `client/` | `public/loco.js` |
+| Assemble | copies all of the above + `bin/loco.js` + `README.md` | `npm-package/` |
+
+The `npm-package/` directory is gitignored — never commit it directly.

package/bin/loco.js

@@ -1,5 +1,44 @@
 #!/usr/bin/env node
 // Loco Translation Manager — CLI entry point
-// Usage: npx loco-translate  OR  loco  (if installed globally)
+// Usage: loco [options]
+//
+// Options:
+//   -p, --port <number>      Port to listen on (default: 6101, or PORT env var)
+//   -d, --data-dir <path>    Directory for loco.db and backups (default: .loco/ in cwd)
+//   -h, --help               Show this help message
 
-import '../dist-server/index.js';
+const args = process.argv.slice(2);
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`
+  Usage: loco [options]
+
+  Options:
+    -p, --port <number>      Port to listen on (default: 6101)
+    -d, --data-dir <path>    Directory for loco.db (default: .loco/ in cwd)
+    -h, --help               Show this help message
+
+  Environment variables (can also be set in a .env file):
+    PORT                     Same as --port
+    LOCO_DATA_DIR            Same as --data-dir
+    BASE_PATH                URL prefix for reverse-proxy deployments
+    BLUEHIVE_API_KEY         BlueHive key for AI translations
+    PUBLIC_URL               Override the printed public URL
+`);
+  process.exit(0);
+}
+
+// Parse --port / -p
+const portIdx = args.findIndex(a => a === '--port' || a === '-p');
+if (portIdx !== -1 && args[portIdx + 1]) {
+  process.env.PORT = args[portIdx + 1];
+}
+
+// Parse --data-dir / -d
+const dataDirIdx = args.findIndex(a => a === '--data-dir' || a === '-d');
+if (dataDirIdx !== -1 && args[dataDirIdx + 1]) {
+  process.env.LOCO_DATA_DIR = args[dataDirIdx + 1];
+}
+
+// Dynamic import so env vars are set before config.ts runs
+await import('../dist-server/index.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hkonda/loco-translate",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Self-hosted translation manager — auto-discovers text, AI translations, Svelte dashboard, CDN client.",
   "type": "module",
   "bin": {