@mahameru/cli 0.0.19 → 0.0.21

package/README.md

@@ -0,0 +1,254 @@
+# MahameruJS CLI Utility
+
+[![npm version](https://img.shields.io/npm/v/mahameru.svg)](https://www.npmjs.com/package/mahameru)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`@mahameru/cli` is the command-line interface for building, running, and managing Mahameru-based applications.
+
+## Installation
+
+Install the CLI globally so the `mahameru` command is available from your terminal:
+
+```bash
+npm install -g @mahameru/cli
+```
+
+If you do not have a MahameruJS project yet, create one with:
+
+```bash
+npm create mahameru
+```
+
+or:
+
+```bash
+npx create-mahameru
+```
+
+## Project Requirements
+
+This CLI expects a `mahameru.config.ts` file in the project root for development mode.
+
+Some commands also rely on these project dependencies:
+
+- `tsx` to load the TypeScript config file for `mahameru dev`
+- `typescript` for the compile step in `mahameru build`
+- `tsc-alias` to rewrite path aliases after compilation
+
+For application source aliases, prefer `tsconfig.json` paths such as `@/*`. Do not rely on `package.json#imports` for `src/**` files that must run from `dist/` in production.
+
+## Command Reference
+
+### `mahameru dev`
+
+Start the MahameruJS development server with hot reload.
+
+```bash
+mahameru dev
+mahameru dev --port 3000
+mahameru dev --host localhost
+```
+
+Options:
+
+- `-p, --port <number>` Port to run the server on
+- `-H, --host <string>` Host to run the server on
+
+Behavior:
+
+- loads `mahameru.config.ts`
+- runs TypeScript typechecking before each start or restart
+- applies default config values when they are not provided
+- runs the Mahameru application from the current project
+- watches `src/**` and `mahameru.config.ts`, then restarts automatically when files change
+
+If typechecking fails, the error is shown in the console and the dev server waits for the next valid save before starting again.
+
+### `mahameru build`
+
+Build the production output for the current project.
+
+```bash
+mahameru build
+```
+
+Behavior:
+
+- runs `tsc --project tsconfig.json`
+- runs `tsc-alias -p tsconfig.json`
+- fails if compiled `dist/**/*.js` files still contain unresolved `@/` or `#/` specifiers
+
+### `mahameru start`
+
+Request the Mahameru Process Manager daemon to start the current project in production mode.
+
+```bash
+mahameru start
+mahameru start --port 8000
+mahameru start --host 127.0.0.1
+```
+
+Options:
+
+- `-p, --port <number>` Port to run the app on. Default: `8000`
+- `-H, --host <string>` Host to run the app on. Default: `127.0.0.1`
+
+Important:
+
+- this command does not directly boot `dist/` by itself
+- it connects to the Mahameru PM daemon over IPC and asks the daemon to fork the current project
+- the daemon must already be running, either through `mahameru pm start` or `mahameru pm service install`
+- on Windows, Mahameru may request elevation automatically when the daemon is running with Administrator privileges
+
+### `mahameru stop`
+
+Request the Mahameru Process Manager daemon to stop the current managed project.
+
+```bash
+mahameru stop
+```
+
+Important:
+
+- this command depends on the Mahameru PM daemon being available
+- it stops the managed project registered under the current package name
+
+### `mahameru status`
+
+Show the status of the current managed project.
+
+```bash
+mahameru status
+```
+
+Important:
+
+- this command depends on the Mahameru PM daemon being available
+- it shows the managed project status, PID, host, port, and root path
+- on Windows, Mahameru may request elevation automatically when connecting to an elevated daemon
+
+## Process Manager
+
+The Process Manager is responsible for hosting managed production apps and exposing a small management server.
+
+### `mahameru pm start`
+
+Start the Mahameru Process Manager manually.
+
+```bash
+mahameru pm start
+mahameru pm start --port 8000 --host 127.0.0.1
+mahameru pm start --cert ./cert.pem --key ./key.pem
+mahameru pm start --daemon
+```
+
+Options:
+
+- `-p, --port <number>` Port to run the server on. Default: `8000`
+- `-H, --host <string>` Host to run the server on. Default: `127.0.0.1`
+- `--cert <string>` Path to the SSL certificate file
+- `--key <string>` Path to the SSL key file
+- `-d, --daemon` Run as a daemon
+
+Notes:
+
+- HTTPS is enabled only when both `--cert` and `--key` are provided
+- the Process Manager serves the management UI and API
+- the Process Manager also restores previously running managed projects on startup when available
+
+### `mahameru pm status`
+
+```bash
+mahameru pm status
+```
+
+This command exists in the CLI, but it is not implemented yet.
+
+### `mahameru pm service install`
+
+Install the Mahameru Process Manager as a system service.
+
+```bash
+mahameru pm service install
+mahameru pm service install --port 8080 --host 127.0.0.1
+mahameru pm service install --cert ./cert.pem --key ./key.pem
+```
+
+Options:
+
+- `-p, --port <number>` Port to run the server on. Default: `8080`
+- `-H, --host <string>` Host to run the server on. Default: `127.0.0.1`
+- `--cert <string>` Path to the SSL certificate file
+- `--key <string>` Path to the SSL key file
+
+Notes:
+
+- this registers the Process Manager to start with the operating system
+- Administrator or root privileges may be required, depending on the platform
+
+### `mahameru pm service uninstall`
+
+Uninstall the Mahameru Process Manager service.
+
+```bash
+mahameru pm service uninstall
+```
+
+Administrator or root privileges may be required.
+
+### `mahameru pm service start`
+
+Start the installed Mahameru Process Manager service.
+
+```bash
+mahameru pm service start
+```
+
+Administrator or root privileges may be required.
+
+### `mahameru pm service stop`
+
+Stop the installed Mahameru Process Manager service.
+
+```bash
+mahameru pm service stop
+mahameru pm service stop --graceful
+```
+
+Options:
+
+- `-g, --graceful` Gracefully stop the service
+
+Administrator or root privileges may be required.
+
+### `mahameru pm service status`
+
+Show the installed service status.
+
+```bash
+mahameru pm service status
+```
+
+This command reports the Process Manager service status for the current platform.
+
+## Recommended Workflow
+
+For local development:
+
+1. Run `mahameru dev`.
+2. Make changes inside `src/**` and let the dev server restart automatically.
+
+For production-style managed runs:
+
+1. Run `mahameru build`.
+2. Start the Process Manager with `mahameru pm start`, or install it with `mahameru pm service install`.
+3. Run `mahameru start` from your project directory to register and start the app through the daemon.
+4. Use `mahameru status` to inspect the managed project.
+5. Use `mahameru stop` to stop it.
+
+## Notes
+
+- If `mahameru.config.ts` is missing, development commands will fail.
+- If `tsx`, `typescript`, or `tsc-alias` are not installed in the project, the related command will fail.
+- `mahameru dev` ignores changes inside `dist/` and `node_modules/`.
+- `mahameru start`, `mahameru stop`, and `mahameru status` are PM-daemon-backed commands, not standalone local process commands.

package/cli.js

@@ -3,7 +3,7 @@
  * ┌────────────────────────────────────────────┐
  * │                                            │
  * │   ▲ MahameruJS - CLI                       │
- * │   Version: 0.0.19                          │
+ * │   Version: 0.0.21                          │
  * │   Built: 2026                              │
  * │                                            │
  * │   Copyright (c) Bintan <hello@bintvn.co>   │
@@ -29,9 +29,9 @@ console.error(n.default.yellow("Please use tsconfig path aliases such as @/* and
 r.succeed(n.default.green(" Build success."))}catch(e){r.fail(n.default.red(" Internal error.")),console.error(e),
 process.exit(1)}}}
 ;const s=o(8330),n=r(o(5205)),i=r(o(8720)),a=o(1455),c=o(6760),l=o(242),d=o(5775),u=o(5412),p=o(5242),f=o(5183),m=o(760)
-},7022(e,t,o){t.dev=function({version:e}){return async({host:t,port:o})=>{console.clear();const i=(0,
-r.ensureDevEnvironment)();(0,s.printCliBanner)(e),await(0,n.startWatchedDevServer)({version:e,environment:i,host:t,
-port:o})}};const r=o(242),s=o(1785),n=o(8320)},3674(e,t,o){var r=this&&this.__importDefault||function(e){
+},7022(e,t,o){t.dev=function({version:e}){return async({host:t,port:o})=>{const a=(0,s.ensureDevEnvironment)();(0,
+n.printCliBanner)(e),o=await(0,r.freePortFinder)(o),await(0,i.startWatchedDevServer)({version:e,environment:a,host:t,
+port:o})}};const r=o(7209),s=o(242),n=o(1785),i=o(8320)},3674(e,t,o){var r=this&&this.__importDefault||function(e){
 return e&&e.__esModule?e:{default:e}};Object.defineProperty(t,"__esModule",{value:!0}),t.install=void 0
 ;const s=o(1421),n=o(3024),i=r(o(5205)),a=o(6760),c=o(6921),l=o(6718),d=o(6471),u=r(o(8720))
 ;t.install=e=>({host:t,port:o,cert:r,key:p})=>{const f="linux"===process.platform,m="win32"===process.platform;let h=""
@@ -170,9 +170,9 @@ return e.includes("Starting compilation in watch mode...")||e.includes("File cha
 function(e){
 return["Starting compilation in watch mode...","File change detected. Starting incremental compilation...","Found 0 errors. Watching for file changes.","Watching for file changes."].some(t=>e.includes(t))
 }(t)||console.log(`${c.default.yellow("[Mahameru TSC]")} ${t}`)}),N=$((0,i.resolve)((0,i.join)(h,"types"))),I=e=>{
-const t=$((0,i.resolve)(e));return t===N||t.startsWith(`${N}/`)},H=C.watchFile?.bind(C)
-;H&&(C.watchFile=(e,t,o,r)=>I(e)?{close(){}}:H(e,t,o,r));const F=C.watchDirectory?.bind(C)
-;F&&(C.watchDirectory=(e,t,o,r)=>I(e)?{close(){}}:F(e,t,o,r));const W=C,J=W.writeFile?.bind(W)??S.writeFile.bind(S)
+const t=$((0,i.resolve)(e));return t===N||t.startsWith(`${N}/`)},F=C.watchFile?.bind(C)
+;F&&(C.watchFile=(e,t,o,r)=>I(e)?{close(){}}:F(e,t,o,r));const H=C.watchDirectory?.bind(C)
+;H&&(C.watchDirectory=(e,t,o,r)=>I(e)?{close(){}}:H(e,t,o,r));const W=C,J=W.writeFile?.bind(W)??S.writeFile.bind(S)
 ;W.writeFile=(e,t,o,r,s,n)=>{J?.(e,t,o,r,s,n),q(e,s)};const U=C.afterProgramCreate;C.afterProgramCreate=e=>{U?.(e)
 ;const t=0===T?1:T;T=t,R=R.then(()=>B(e,t)).catch(e=>{
 console.error(c.default.red("[Mahameru Dev] Build lifecycle failed.")),console.error(e)})};const L=u(C)
@@ -200,11 +200,11 @@ i.resolve)(e.fileName)).filter(e=>{const o=$(e);return o.startsWith(t)&&o.endsWi
 }(t))s.changedRuntimeSourceFiles.add(e)}}try{return await k,L}catch(e){throw L.close(),e}}({environment:e,spinner:k,
 onBuildStart:()=>{T=!0},
 onBuildSuccess:({durationMs:e,emittedRuntimeFiles:t,changedRuntimeSourceFiles:o,initialBuild:r})=>{if(b=e,T=!1,!r){
-for(const e of t)D.add(e);for(const e of o)O.add(e)}T||!u?.initialized||E||(x||A||0!==D.size)&&F()},onBuildFailure:()=>{
+for(const e of t)D.add(e);for(const e of o)O.add(e)}T||!u?.initialized||E||(x||A||0!==D.size)&&H()},onBuildFailure:()=>{
 T=!1,b=0,A=!1,D.clear(),O.clear(),j&&(clearTimeout(j),j=null)}
 }),k.succeed(`${c.default.green("[Mahameru]")} Initial build completed.\n`),await u.start()
-;const N=new l.Watchman([h,P]),I=new l.Watchman(y);let H=Promise.resolve();const F=()=>{j&&clearTimeout(j),
-j=setTimeout(()=>{H=H.then(async()=>{if(E||!u)return;if(T)return void F();const e=[...D],t=[...O],o=A,r=x;if(x=!1,A=!1,
+;const N=new l.Watchman([h,P]),I=new l.Watchman(y);let F=Promise.resolve();const H=()=>{j&&clearTimeout(j),
+j=setTimeout(()=>{F=F.then(async()=>{if(E||!u)return;if(T)return void H();const e=[...D],t=[...O],o=A,r=x;if(x=!1,A=!1,
 D.clear(),
 O.clear(),j=null,r)return console.log(c.default.yellow("\n [Mahameru] Config file changed. Reloading server...\n")),
 await u.stop(),u=new d.App(C),console.clear(),void await u.start();if(0===e.length&&!o)return
@@ -216,7 +216,7 @@ console.error(c.default.red("[Mahameru Dev] Hot reload failed.")),console.error(
 i.resolve)(g)),n=$((0,i.resolve)(P));if(!o.startsWith(`${r}/`)&&o!==n)return null
 ;if(o.endsWith(".d.ts")||o.endsWith(".map")||o.endsWith(".tsbuildinfo"))return null;if(o===n)return"config"
 ;if(!o.endsWith(".js"))return null;if(o.startsWith(`${s}/`))return"runtime";return null}(t)
-;o&&("runtime"===o&&"delete"!==e&&"rename"!==e||((e,t)=>{"config"===e?x=!0:(D.add(t),O.add(S(t))),T||F()})(o,t))}),
+;o&&("runtime"===o&&"delete"!==e&&"rename"!==e||((e,t)=>{"config"===e?x=!0:(D.add(t),O.add(S(t))),T||H()})(o,t))}),
 I.on("all",async({event:e,filePath:t,oldFilePath:o})=>{if("delete"!==e&&"rename"!==e)return;const r="rename"===e&&o?o:t
 ;(function(e){const t=`${$((0,i.resolve)(y))}/`;return $((0,i.resolve)(e)).startsWith(t)})(r)&&(await async function(e){
 const t=(0,i.resolve)(e),o=(0,i.relative)(y,t);if(o.startsWith(".."))return;if(/\.[^\\/]+$/.test(o)){
@@ -224,7 +224,7 @@ const e=function(e){const t=(0,i.relative)(y,e);return(0,i.resolve)(g,t.replace(
 ;return void await Promise.all([(0,n.rm)(e,{force:!0}).catch(()=>{}),(0,n.rm)(`${e}.map`,{force:!0}).catch(()=>{}),(0,
 n.rm)(e.replace(/\.js$/i,".d.ts"),{force:!0}).catch(()=>{}),(0,n.rm)(e.replace(/\.js$/i,".d.ts.map"),{force:!0
 }).catch(()=>{})])}await(0,n.rm)((0,i.resolve)(g,o),{recursive:!0,force:!0}).catch(()=>{})}(r),A=!0,O.add((0,
-i.resolve)(r)),T||F())}),await N.start(),await I.start();const W=async(e=0)=>{E||(E=!0,j&&(clearTimeout(j),j=null),
+i.resolve)(r)),T||H())}),await N.start(),await I.start();const W=async(e=0)=>{E||(E=!0,j&&(clearTimeout(j),j=null),
 N.stop(),I.stop(),await u.stop(),M?.close(),process.exit(e))};process.once("SIGINT",()=>{W(0)}),
 process.once("SIGTERM",()=>{W(0)}),await new Promise(()=>{})}
 ;const s=o(3024),n=o(1455),i=o(6760),a=r(o(8720)),c=r(o(5205)),l=o(6469),d=o(1205),u=o(8995),p=o(5183),f=(0,
@@ -457,7 +457,7 @@ var r=this&&this.__importDefault||function(e){return e&&e.__esModule?e:{default:
 ;const s=o(6858),n=r(o(5205)),i=o(8330),a=o(7022),c=o(545),l=o(5775),d=o(3674),u=o(6478),p=o(6571),f=o(1471),m=o(5019),h=o(7659),g=o(846),y=o(7695),v=o(2074),P=new s.Command
 ;(async()=>{try{const e=process.cwd(),t="mahameru-pm"
 ;P.name("mahameru").description(`${n.default.bold(n.default.cyan("▲ MahameruJS"))} ${n.default.dim(`CLI v${i.version}`)}`).version(i.version,"-v, --version","Display help for command"),
-P.command("dev").description("Start MahameruJS development server.").option("-p, --port <number>","Port to run the server on",l.parsePort).option("-H, --host <string>","Host to run the server on").action((0,
+P.command("dev").description("Start MahameruJS development server.").option("-p, --port <number>","Port to run the server on",l.parsePort,3e3).option("-H, --host <string>","Host to run the server on","127.0.0.1").action((0,
 a.dev)({version:i.version})),P.command("build").description("Build MahameruJS production application.").action((0,
 c.build)({rootPath:e
 })),P.command("start").description("Start MahameruJS production server.").option("-p, --port <number>","Port to run the server on",l.parsePort,8e3).option("-H, --host <string>","Host to run the server on","127.0.0.1").action((0,
@@ -538,17 +538,17 @@ o.write(JSON.stringify({success:!0,message:`Project ${r} successfully started by
 mpmUrl:`http://${e}:${t}`}));else if("PROCESS_USAGE"===n){const e=(0,h.getProject)(r);e&&G.emit("process-usage",{data:i,
 project:(0,g.parseProject)(e)})}},D=e=>t=>{console.log(`[MPM] Project ${e} errored: ${t.message}`)},O=e=>({success:!0,
 data:e}),R=e=>({success:!1,error:e}),k=e=>(0,g.parseProject)(e),C=()=>(0,h.getProjects)().map(g.parseProject),N=e=>{
-console.log(`[MPM] ${e}`)},I=()=>{G.emit("projects",C())},H=e=>{
+console.log(`[MPM] ${e}`)},I=()=>{G.emit("projects",C())},F=e=>{
 const t=(0,d.join)(e.rootPath,"node_modules","mahameru","dist","server.js");if(!(0,
 v.existsSync)(t))throw new Error(`Mahameru package is not installed in ${e.rootPath} project. Please install it by running: npm install mahameru`)
-;return t},F=e=>({MAHAMERU__SEND_PROCESS_USAGE_INTERVAL:"3000",MAHAMERU__ROOT_PATH:e.rootPath,
+;return t},H=e=>({MAHAMERU__SEND_PROCESS_USAGE_INTERVAL:"3000",MAHAMERU__ROOT_PATH:e.rootPath,
 MAHAMERU__MODE:"production",...e.host?{MAHAMERU__HTTP_LISTEN_HOST:e.host.trim()}:{},...e.port?{
 MAHAMERU__HTTP_LISTEN_PORT:e.port.toString().trim()}:{}}),W=(e,t,o=null)=>{t.stdout?.on("data",T(e.name)),
 t.stderr?.on("data",A(e.name)),t.on("message",b(o,e.name,t)),t.on("error",D(e.name)),t.once("exit",o=>{e.child===t&&(0,
 h.getProject)(e.name)&&(e.status=0===o||null===o?"stopped":"errored",e.pid=void 0,e.child=void 0,
 G.emit("project-update",k(e)),I())})},J=(e,t)=>new Promise(o=>{const r=s=>{t.includes(s.type)&&(e.off("message",r),o(s))
-};e.on("message",r)}),U=(e,t=null)=>new Promise((o,r)=>{let s=!1;const n=e=>{s||(s=!0,e())};try{const s=H(e),i=(0,
-l.fork)(s,[],{cwd:e.rootPath,env:{...process.env,...F(e)},stdio:["inherit","pipe","pipe","ipc"]});e.status="stopped",
+};e.on("message",r)}),U=(e,t=null)=>new Promise((o,r)=>{let s=!1;const n=e=>{s||(s=!0,e())};try{const s=F(e),i=(0,
+l.fork)(s,[],{cwd:e.rootPath,env:{...process.env,...H(e)},stdio:["inherit","pipe","pipe","ipc"]});e.status="stopped",
 e.pid=i.pid,e.child=i,(0,h.setProject)(e),W(e,i,t),J(i,["READY","ERROR"]).then(({type:t,data:s})=>{"READY"===t?n(()=>{
 e.status="running",e.pid=i.pid,e.child=i,(0,h.setProject)(e),o(e)}):"ERROR"===t&&n(()=>{e.status="errored",e.pid=void 0,
 e.child=void 0,(0,h.setProject)(e),r(new Error("string"==typeof s?s:`Failed to start project ${e.name}`))})}),
@@ -612,11 +612,13 @@ t.getProjects)().map(e=>({...e,child:void 0,pid:void 0,isLastStatusIsRunning:"ru
 throw new Error("Failed to save projects")}}},7209(e,t,o){var r=this&&this.__importDefault||function(e){
 return e&&e.__esModule?e:{default:e}};Object.defineProperty(t,"__esModule",{value:!0}),
 t.freePortFinder=async function(e=3e3){let t=e;const o=e+999;for(;t<o;)try{return await n(t)}catch(e){t++}
-throw new Error(`Port ${e} - 999 is not available`)};const s=r(o(7030));function n(e){return new Promise((t,o)=>{
-const r=s.default.createServer();r.once("error",e=>{e.code,o(e)}),r.once("listening",()=>{r.close(()=>t(e))}),
-r.listen(e,"127.0.0.1")})}},4830(e,t,o){t.getProjectJson=async function(e){try{return JSON.parse(await(0,r.readFile)((0,
-s.join)(e,"package.json"),"utf-8"))}catch(e){throw new Error("package.json not found")}};const r=o(1455),s=o(6760)},
-6718(e,t,o){t.getNodeModulesPath=function(){try{return(0,r.execSync)("npm root -g",{stdio:["ignore","pipe","ignore"]
+throw new Error(`Port ${e} - 999 is not available`)},t.isPortAvailable=function(e){return new Promise((t,o)=>{
+const r=s.default.createServer();r.once("error",e=>{e.code,o(!1)}),r.once("listening",()=>{r.close(()=>t(!0))}),
+r.listen(e,"127.0.0.1")})};const s=r(o(7030));function n(e){return new Promise((t,o)=>{const r=s.default.createServer()
+;r.once("error",e=>{e.code,o(e)}),r.once("listening",()=>{r.close(()=>t(e))}),r.listen(e,"127.0.0.1")})}},4830(e,t,o){
+t.getProjectJson=async function(e){try{return JSON.parse(await(0,r.readFile)((0,s.join)(e,"package.json"),"utf-8"))
+}catch(e){throw new Error("package.json not found")}};const r=o(1455),s=o(6760)},6718(e,t,o){
+t.getNodeModulesPath=function(){try{return(0,r.execSync)("npm root -g",{stdio:["ignore","pipe","ignore"]
 }).toString().trim()}catch(e){throw new Error("npm is not installed or not accessible on your system.")}}
 ;const r=o(1421)},4813(e,t,o){t.isMahameruProjectDir=function(e){const t=(0,s.join)(e,"package.json"),o=(0,
 s.join)(e,"node_modules");if(!(0,r.existsSync)(t)&&(0,r.existsSync)(o))return!1;try{const e=(0,
@@ -643,6 +645,6 @@ e.exports=require("module")},9278(e){e.exports=require("net")},1421(e){e.exports
 e.exports=require("node:cluster")},3024(e){e.exports=require("node:fs")},1455(e){e.exports=require("node:fs/promises")},
 7067(e){e.exports=require("node:http")},4708(e){e.exports=require("node:https")},8995(e){
 e.exports=require("node:module")},7030(e){e.exports=require("node:net")},8161(e){e.exports=require("node:os")},6760(e){
-e.exports=require("node:path")},6928(e){e.exports=require("path")},8330(e){e.exports={version:"0.0.19"}}};const t={}
+e.exports=require("node:path")},6928(e){e.exports=require("path")},8330(e){e.exports={version:"0.0.21"}}};const t={}
 ;(function o(r){const s=t[r];if(void 0!==s)return s.exports;const n=t[r]={exports:{}}
 ;return e[r].call(n.exports,n,n.exports,o),n.exports})(8625)})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mahameru/cli",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "description": "MahameruJS CLI Utility - The command-line interface for running and building Mahameru-based applications",
   "bin": {
     "mahameru": "./cli.js"