@master4n/master-cli 2.3.0 → 3.0.0

package/bin/interface/index.d.ts

@@ -1,3 +1,2 @@
-export * from './HRAInput';
 export * from './InquirerPrompt';
 export * from './ProcessInfo';

package/bin/logo/draw.d.ts

@@ -1,2 +1,8 @@
-/**Display the welcome art and message*/
+/**
+ * The welcome banner — master-cli's signature.
+ *
+ * Rendered only on an interactive terminal (and never with `--json`), and
+ * written to **stderr**, so stdout stays a clean machine-readable channel for
+ * agents while humans still get the full experience.
+ */
 export declare const logoWelcome: () => Promise<void>;

package/bin/utility/index.d.ts

@@ -1,4 +1,3 @@
-import { InquirerOptions } from '../interface';
 export declare function Logger(): {
     info: (info: string) => void;
     warn: (warn: string) => void;
@@ -9,42 +8,22 @@ export declare function CommandBuilder(instance: any): {
     add: (alias: string, describe: string, builder: object, handler: (argv: any) => any) => void;
 };
 /**
- * Function to get the current user's name based on the operating system
- * @returns user
+ * Get the current user's name based on the operating system.
  */
 export declare function getCurrentUserName(): string;
 /**
- * Function to create a hidden cache directory
+ * Create the hidden cache directory (`~/.mfn/cache`) if it doesn't exist.
  */
 export declare function createHiddenCacheDirectory(): void;
 /**
- * Get the location of cache directory.
- * @returns cacheDir.
+ * Get the location of the cache directory (`~/.mfn/cache`).
  */
 export declare function getCacheDirectory(): string;
 /**
- * Validate arugment of type numbers and range of 1 to 1000.
- * @param args
- * @returns true if valid number
+ * Validate argument(s) of type number within the range 1 to 1000.
+ * @returns true if every argument is a valid in-range number.
  */
 export declare function validateNumberArguments(...args: number[]): boolean;
-/**
- * Validate arugment of type numbers.
- * @param args
- * @returns true if valid number
- */
-export declare function validatePositiveNumber(...args: number[]): boolean;
-/**
- * Currency formatter function
- * @param value
- * @param currency
- * @param locale
- * @returns
- */
-export declare function formatCurrency(value: number, currency?: string, locale?: string): string;
-export declare function inquirerPrompt(options: Array<InquirerOptions>): Promise<any>;
 export declare function getLatestVersion(packageName: string): string;
-export declare function installDependencies(command: string, projectPath: any, spinner: any): void;
-export declare function getDefaultPackageContent(moduleType: string, path: any, projectPath: any): {};
 export declare const colorQuestions: (message: string) => string;
 export declare function saveIgnoresToCache(ignore: any, cachePath: any): Promise<void>;

package/bin/utility/io.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared I/O for AI-agent-friendly AND human-friendly commands.
+ *
+ * Contract every command follows:
+ *  - **Headless first**: runs from flags/stdin; an interactive prompt is only a
+ *    fallback when stdout is a TTY and required input is missing.
+ *  - **Machine-readable**: with `--json`, or whenever stdout is NOT a TTY (piped
+ *    into an agent/file), the command prints exactly one JSON object to stdout:
+ *    success → `{ "ok": true, ... }`, failure → `{ "ok": false, "error", "message" }`.
+ *  - **Human-friendly**: on a TTY without `--json`, it renders the rich/coloured
+ *    output instead.
+ *  - **Stable exit codes**: `0` success, non-zero on failure.
+ *
+ * Logs/spinners/banners go to **stderr** (see Logger) so stdout stays a clean
+ * data channel for agents.
+ */
+/** True when stdout is an interactive terminal. */
+export declare const isTTY: () => boolean;
+/** Add the standard `--json` option to a yargs builder. */
+export declare const withJsonFlag: (yargs: any) => any;
+/** Should this invocation produce JSON? (explicit flag, or non-TTY stdout). */
+export declare const wantsJson: (argv: {
+    json?: boolean;
+}) => boolean;
+/**
+ * Emit a successful result. In JSON mode prints `{ ok: true, ...data }`;
+ * otherwise calls `renderHuman` for the pretty output. Returns exit code 0.
+ */
+export declare function emit(argv: {
+    json?: boolean;
+}, data: Record<string, unknown>, renderHuman: () => void): void;
+/**
+ * Emit a failure and exit with `code` (default 1). In JSON mode prints
+ * `{ ok: false, error, message }` on stdout; otherwise logs the message to
+ * stderr. Never returns.
+ *
+ * @param error   short stable machine code, e.g. `"InvalidInput"`.
+ * @param message human-readable explanation.
+ */
+export declare function fail(argv: {
+    json?: boolean;
+}, error: string, message: string, code?: number): never;
+/** True when a TTY-interactive fallback is appropriate (TTY and not --json). */
+export declare const canPrompt: (argv: {
+    json?: boolean;
+}) => boolean;
+/**
+ * Read all of stdin as a UTF-8 string. Returns '' immediately when stdin is a
+ * TTY (nothing piped). Lets commands accept input via `echo x | mfn ...`.
+ */
+export declare function readStdin(): Promise<string>;
+/**
+ * Emit a `{ ok: false, error, message }` failure and exit, WITHOUT a parsed
+ * argv. Used by the yargs `.fail()` handler, where errors originate in the
+ * parser layer (missing required arg, unknown command/flag, coerce throw)
+ * before a command's own `fail()` can run. JSON mode is inferred from
+ * `--json` in argv or a non-TTY stdout. Never returns.
+ */
+export declare function failEnvelope(error: string, message: string, code?: number): never;

package/llms.txt

@@ -0,0 +1,58 @@
+# @master4n/master-cli (`mfn`)
+
+> A headless-friendly developer CLI that replaces boilerplate agents otherwise
+> regenerate on every machine: epoch/date conversions, JWT decoding, freeing
+> ports, finding files, and printing directory trees. Every command is designed
+> to be called by both humans and AI agents.
+
+## Agent contract (read this first)
+
+- **Discover commands:** `mfn capabilities --json` returns the full manifest
+  (`{ name, version, bin, conventions, commands:[{name,summary,examples}] }`).
+- **Machine output:** pass `--json`, OR just pipe the command (when stdout is not
+  a TTY the CLI auto-emits JSON). Output is exactly one object on stdout:
+  success → `{ "ok": true, ... }`, failure → `{ "ok": false, "error", "message" }`.
+- **Exit codes:** `0` success · `1` runtime error · `2` usage error.
+- **Clean channels:** the welcome banner, spinners, and logs go to **stderr**;
+  **stdout carries only the JSON result**, so `mfn <cmd> --json | jq` always works.
+- **No prompts in headless mode:** interactive prompts appear only on a TTY when
+  required input is missing; with `--json` or when piped, commands never block.
+- **Strict parsing:** unknown commands, unknown flags, and missing required
+  arguments are rejected with `{ "ok": false, "error": "UsageError", ... }` and
+  exit `2` — a typo never silently "succeeds".
+
+## Commands
+
+- `mfn id [-t uuid|uuid7|nano] [-n count] [--size N] --json` — generate ids. UUID v4
+  (default), time-ordered UUID v7 (RFC 9562), or a URL-safe nano id. Returns `{ type, count, ids }`.
+- `mfn hash [text] [-a md5|sha1|sha256|sha512] [-f file] [-e hex|base64|base64url] --json`
+  — hash a string, a file, or piped stdin. Returns `{ algo, encoding, source, bytes, hash }`.
+- `mfn encode [text] [--as base64|base64url|hex|url] [-d] --json` — encode (or `-d` decode)
+  text or stdin. Returns `{ operation, codec, input, output }`.
+- `mfn random [-b bytes] [-e hex|base64|base64url] | [-p [-l length]] --json` — secure random
+  bytes, or an unbiased password. Returns `{ kind, ..., value }`.
+- `mfn port [--json] | [-c port] | [-n count]` — find free port(s), or check a specific port.
+  Returns `{ port }` / `{ count, ports }` / `{ port, available }`.
+- `mfn epoch <value> [--tz] [--format] --json` — epoch → date (unit auto-detected:
+  s/ms/µs/ns). `mfn epoch --from <dateString> [--format] [--tz] --json` — date → epoch.
+  Fractional/invalid epochs fail with exit 1.
+- `mfn date [from] [--tz] [--format] [--in-format] [--in-tz] --json` — convert/format
+  a date across timezones; omit `from` for now. Returns epoch + UTC + target-zone.
+- `mfn decode -t <jwt> --json` — decode a JWT's header and payload (signature NOT verified).
+  If the payload has a numeric `exp`, also returns `expiry: { exp, expired, expiresInSeconds }`.
+- `mfn kill -p <port...> [-y] --json` — kill the process(es) listening on the given
+  ports. Headless/`--json` (and `-y`) kill all matches without prompting; in headless
+  mode you MUST pass `-p` (no cached-port replay). Returns `{ killed, failed, notFound }`.
+- `mfn sc [pattern] [--ignore...] [--depth] [--limit] --json` — fuzzy-find files/folders
+  under the current directory. Returns `{ pattern, root, count, truncated, matches }`.
+- `mfn cts [--type text|svg|png|jpeg] [--ignore...] --json` — print the directory tree as
+  text (default) or export it to an image. Ignores node_modules/.git/.nx by default.
+- `mfn update [package] --json` — update the CLI (or a named package) globally via npm.
+- `mfn capabilities --json` — self-describing manifest of all of the above.
+
+## Notes
+
+- Time/date features are powered by `@master4n/temporal-transformer` v2 (Luxon-backed,
+  integer epochs; Luxon format tokens, e.g. `yyyy-MM-dd HH:mm:ss`).
+- Zero shell interpolation: process/port/package operations use `execFile` (no shell),
+  so inputs cannot inject commands.

package/package.json

@@ -1,68 +1,65 @@
 {
   "name": "@master4n/master-cli",
-  "version": "2.3.0",
-  "description": "Command Line Interface For Various Useful Operations",
-  "main": "./bin/index.js",
-  "types": "./bin/index.d.ts",
+  "version": "3.0.0",
+  "description": "AI-agent-friendly command-line toolkit: timestamp/date conversion, JWT decoding, port killing, file finding, and directory trees — headless, --json, with a self-describing manifest.",
   "type": "module",
-  "bin": {
-    "mfn": "./bin/index.js"
-  },
-  "scripts": {
-    "clean": "rimraf dist",
-    "lint": "eslint src/**/*.ts",
-    "format": "prettier --write src/**/*.ts",
-    "build": "npm run clean && rollup --config"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Master4Novice/common.git"
+    "url": "git+https://github.com/Master4Novice/master-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Master4Novice/master-cli/issues"
   },
   "keywords": [
     "cli",
-    "helper",
-    "module"
+    "command-line",
+    "command-line-tool",
+    "developer-tools",
+    "devtools",
+    "nodejs",
+    "typescript",
+    "ai-agents",
+    "agent-tools",
+    "llm-tools",
+    "automation",
+    "headless",
+    "json-output",
+    "jwt",
+    "jwt-decode",
+    "epoch",
+    "epoch-converter",
+    "unix-timestamp",
+    "timezone",
+    "kill-port",
+    "free-port",
+    "directory-tree",
+    "fuzzy-finder",
+    "mfn",
+    "master-cli"
   ],
   "author": "dwivna",
   "license": "MIT",
-  "homepage": "",
-  "publishConfig": {
-    "directory": "dist",
-    "access": "public"
-  },
+  "homepage": "https://github.com/Master4Novice/master-cli#readme",
   "contributors": [
     {
       "name": "dwivna"
     }
   ],
   "dependencies": {
-    "@master4n/temporal-transformer": "^1.0.9",
-    "@types/fs-extra": "^11.0.4",
-    "@types/yargs": "^17.0.32",
+    "@master4n/temporal-transformer": "^2.0.4",
     "boxen": "^7.1.1",
     "chalk": "^5.3.0",
     "figlet": "^1.7.0",
     "fs-extra": "^11.2.0",
     "fuzzy": "^0.1.3",
     "inquirer": "^9.2.23",
-    "inquirer-autocomplete-prompt": "^3.0.1",
-    "inquirer-date-prompt": "^3.0.0",
-    "inquirer-fuzzy-path": "^2.3.0",
-    "is-root": "^3.0.0",
-    "moment": "^2.30.1",
-    "moment-timezone": "^0.5.45",
-    "open": "^10.1.0",
+    "ora": "^8.0.1",
     "sharp": "^0.33.4",
-    "update-notifier": "^7.0.0",
     "yargs": "^17.7.2"
   },
-  "devDependencies": {
-    "@types/figlet": "^1.5.8",
-    "@types/inquirer": "^9.0.7",
-    "@types/inquirer-fuzzy-path": "^2.3.9",
-    "@types/node": "^20.12.12",
-    "@types/update-notifier": "^6.0.8",
-    "ora": "^8.0.1"
-  },
-  "gitHead": "2ef1d0cbf62f6f2742140d6e47cfb1ade721f180"
-}
+  "main": "bin/index.js",
+  "types": "bin/index.d.ts",
+  "bin": {
+    "mfn": "bin/index.js"
+  }
+}

package/bin/commands/create.d.ts

@@ -1,7 +0,0 @@
-declare const createApolloExpress: {
-    command: string;
-    describe: string;
-    builder: (yargs: any) => any;
-    handler: (argv: any) => Promise<void>;
-};
-export default createApolloExpress;

package/bin/commands/hra.d.ts

@@ -1,7 +0,0 @@
-declare const hra: {
-    command: string;
-    describe: string;
-    builder: (yargs: any) => void;
-    handler: (argv: any) => void;
-};
-export default hra;

package/bin/commands/md.d.ts

@@ -1,7 +0,0 @@
-declare const md: {
-    command: string;
-    describe: string;
-    builder: (yargs: any) => void;
-    handler: (argv: any) => void;
-};
-export default md;

package/bin/commands/sr.d.ts

@@ -1,7 +0,0 @@
-declare const sr: {
-    command: string;
-    describe: string;
-    builder: (yargs: any) => void;
-    handler: (argv: any) => void;
-};
-export default sr;

package/bin/constants/contents/comjs-content.d.ts

@@ -1,3 +0,0 @@
-export declare const comjsIndexContent = "const express = require('express');\nconst { ApolloServer } = require('@apollo/server');\nconst { expressMiddleware } = require('@apollo/server/express4');\nconst { readFileSync } = require('fs');\nconst { join } = require('path');\nconst cors = require('cors');\n  \nconst getSchema = () => {\n    const schemaPath = join(process.cwd(), `resources/schema.graphql`);\n    return readFileSync(schemaPath, 'utf-8');\n};\n  \nconst typeDefs = getSchema();\n  \nconst resolvers = {\n    Query: {\n      hello: () => 'Hello world!',\n    },\n};\n  \nconst app = express();\n\nconst server = new ApolloServer({\n    typeDefs,\n    resolvers,\n});\n  \nserver.start().then(() => {\n    app.use('/graphql', cors(), express.json(), expressMiddleware(server));\n});\n  \napp.listen(4000, () => {\n    console.log('\uD83D\uDE80 Server ready at http://localhost:4000/graphql');\n});\n";
-export declare const comjsIndexContentVersion = "const express = require('express');\nconst { ApolloServer } = require('@apollo/server');\nconst { expressMiddleware } = require('@apollo/server/express4');\nconst { versionMiddleware } = require('./versionMiddleware.js');\n\nconst app = express();\n\napp.use(versionMiddleware);\n\napp.use('/graphql', express.json(), async (req, res, next) => {\n    const { typeDefs, resolvers } = req.app.locals;\n    const server = new ApolloServer({\n       typeDefs,\n       resolvers,\n    });\n    await server.start();\n    expressMiddleware(server)(req, res, next);\n});\n\napp.listen(4000, () => {\n   console.log(\u2018\uD83D\uDE80 Server ready at http://localhost:4000/graphql\u2019);\n});\n";
-export declare const comjsMiddleContent = "const { readFileSync } = require('fs');\nconst { join } = require('path');\nconst { resolvers: resolversV1 } = require('./v1/resolvers.js');\nconst { resolvers: resolversV2 } = require('./v2/resolvers.js');\n\nconst getSchema = (version) => {\n    const schemaPath = join(process.cwd(), `resources/${version}/schema.graphql`);\n    return readFileSync(schemaPath, 'utf8');\n};\n\nconst versionMiddleware = (req, res, next) => {\n    const version = req.headers['api-version'];\n\n    if (version === 'v1') {\n      req.app.locals.typeDefs = getSchema('v1');\n      req.app.locals.resolvers = resolversV1;\n    } else if (version === 'v2') {\n      req.app.locals.typeDefs = getSchema('v2');\n      req.app.locals.resolvers = resolversV2;\n    } else {\n      res.status(400).send('Unsupported or missing API version');\n      return;\n    }\n    next();\n};\n\nmodule.exports = { versionMiddleware };\n";

package/bin/constants/contents/index.d.ts

@@ -1,3 +0,0 @@
-export * from './comjs-content';
-export * from './type-content';
-export * from './md-contents';

package/bin/constants/contents/md-contents.d.ts

@@ -1 +0,0 @@
-export declare const apolloContent: (projectName: string, moduleType: string) => string;

package/bin/constants/contents/type-content.d.ts

@@ -1,3 +0,0 @@
-export declare const typeIndexContent = "import express from 'express';\nimport { ApolloServer } from '@apollo/server';\nimport { expressMiddleware } from '@apollo/server/express4';\nimport cors from 'cors';\nimport { readFileSync } from 'fs';\nimport { join } from 'path';\n\nconst getSchema = (): string => {\n    const schemaPath = join(process.cwd(), `resources/schema.graphql`);\n    return readFileSync(schemaPath, 'utf-8');\n};\n\nconst typeDefs = getSchema();\n\nconst resolvers = {\n    Query: {\n        hello: () => 'Hello world!',\n    },\n};\n\nconst app = express();\n\nconst server = new ApolloServer({\n    typeDefs,\n    resolvers\n});\n\nawait server.start();\n\napp.use('/graphql', cors<cors.CorsRequest>(), express.json(), expressMiddleware(server));\n\napp.listen(4000, () => {\n    console.log('\uD83D\uDE80 Server ready at http://localhost:4000/graphql');\n});\n";
-export declare const typeIndexContentVersion = "import express from 'express';\nimport { ApolloServer } from '@apollo/server';\nimport { expressMiddleware } from '@apollo/server/express4';\nimport { versionMiddleware } from './versionMiddleware.js';\n\nconst app = express();\n\napp.use(versionMiddleware);\n\napp.use('/graphql', express.json(), async (req, res, next) => {\n     const { typeDefs, resolvers } = req.app.locals;\n     const server = new ApolloServer({\n         typeDefs,\n         resolvers,\n     });\n\n     await server.start();\n     expressMiddleware(server)(req, res, next);\n});\n\napp.listen(4000, () => {\n     console.log('\uD83D\uDE80 Server ready at http://localhost:4000/graphql');\n});\n";
-export declare const typeMiddleContent = "import { Request, Response, NextFunction } from 'express';\nimport { readFileSync } from 'fs';\nimport { join } from 'path';\nimport { resolvers as resolversV1 } from './v1/resolvers.js';\nimport { resolvers as resolversV2 } from './v2/resolvers.js';\n  \nconst getSchema = (version: string): string => {\n    const schemaPath = join(process.cwd(), `resources/${version}/schema.graphql`);\n    return readFileSync(schemaPath, 'utf8');\n};\n  \nexport const versionMiddleware = (req: Request, res: Response, next: NextFunction) => {\n    const version = req.headers['api-version'];\n  \n    if (version === 'v1') {\n      req.app.locals.typeDefs = getSchema('v1');\n      req.app.locals.resolvers = resolversV1;\n    } else if (version === 'v2') {\n      req.app.locals.typeDefs = getSchema('v2');\n      req.app.locals.resolvers = resolversV2;\n    } else {\n      res.status(400).send('Unsupported or missing API version');\n      return;\n    }\n    next();\n};\n";

package/bin/constants/graphql-express-contants.d.ts

@@ -1,5 +0,0 @@
-export declare const schema = "type Query {\n  hello: String\n}\n";
-export declare const schemaV1 = "type User {\n    id: ID!\n    firstName: String\n    lastName: String\n}\n\ntype Query {\n    getUser(id: ID!): User\n    allUsers: [User]\n}\n";
-export declare const resolversV1: (typescript: any) => "export const resolvers = {\n    Query: {\n      getUser: (parent: any, args: { id: string }) => {\n        // Mock data for v1\n        return { id: args.id, firstName: 'John', lastName: 'Doe' };\n      },\n      allUsers: () => {\n        // Mock data for v1\n        return [{ id: '1', firstName: 'John', lastName: 'Doe' }];\n      },\n    },\n  };\n  " | "exports.resolvers = {\n    Query: {\n      getUser: (parent, args) => {\n        // Mock data for v1\n        return { id: args.id, firstName: 'John', lastName: 'Doe' };\n      },\n      allUsers: () => {\n        // Mock data for v1\n        return [{ id: '1', firstName: 'John', lastName: 'Doe' }];\n      },\n    },\n  };\n";
-export declare const schemaV2 = "type User {\n    id: ID!\n    firstName: String\n    lastName: String\n    age: Int\n  }\n  \n  type Query {\n    getUser(id: ID!): User\n    allUsers: [User]\n    usersByAge(age: Int!): [User]\n  }\n";
-export declare const resolversV2: (typescript: any) => "export const resolvers = {\n    Query: {\n      getUser: (parent: any, args: { id: string }) => {\n        // Mock data for v2\n        return { id: args.id, firstName: 'John', lastName: 'Doe', age: 30 };\n      },\n      allUsers: () => {\n        // Mock data for v2\n        return [{ id: '1', firstName: 'John', lastName: 'Doe', age: 30 }];\n      },\n      usersByAge: (parent: any, args: { age: number }) => {\n        // Mock data for v2\n        return [{ id: '1', firstName: 'John', lastName: 'Doe', age: args.age }];\n      },\n    },\n  };\n  " | "exports.resolvers = {\n    Query: {\n      getUser: (parent, args) => {\n        // Mock data for v2\n        return { id: args.id, firstName: 'John', lastName: 'Doe', age: 30 };\n      },\n      allUsers: () => {\n        // Mock data for v2\n        return [{ id: '1', firstName: 'John', lastName: 'Doe', age: 30 }];\n      },\n      usersByAge: (parent, args) => {\n        // Mock data for v2\n        return [{ id: '1', firstName: 'John', lastName: 'Doe', age: args.age }];\n      },\n    },\n  };\n";

package/bin/interface/HRAInput.d.ts

@@ -1,6 +0,0 @@
-export interface HRAInput {
-    monthlyBasic: number;
-    monthlyRent: number;
-    hraReceived: number;
-    isMetro: boolean;
-}