@master4n/master-cli 3.0.2 → 3.0.3

package/bin/interface/CliCommand.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shape every command module exports and `src/index.ts` registers. Typing the
+ * registration (instead of `any`) means a malformed command module fails the
+ * typecheck instead of failing at runtime.
+ */
+export interface CliCommand {
+    /** yargs command spec, e.g. `epoch <value>` or `sc [pattern]`. */
+    command: string;
+    /** One-line description shown in `mfn -h`. */
+    describe: string;
+    /** yargs builder adding the command's options/examples. */
+    builder: (yargs: any) => any;
+    /** Command implementation; receives parsed argv. */
+    handler: (argv: any) => void | Promise<void>;
+}

package/bin/interface/index.d.ts

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

package/bin/utility/guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * True when reading this file's CONTENT would expose credentials/keys/PII.
+ * Checks the literal path AND the resolved realpath, so an innocently named
+ * symlink ("notes.txt" → "~/.ssh/id_rsa") can't smuggle a secret past the
+ * basename check (found by an adversarial review).
+ */
+export declare function isSensitivePath(p: string): boolean;
+/** Standard refusal message for a sensitive path (stable error: SensitivePath). */
+export declare const sensitivePathMessage: (p: string) => string;
+/** Returns what kind of secret the text contains, or null when none detected. */
+export declare function scanSecrets(text: string): string | null;
+/**
+ * Mask secret-shaped substrings inside text that a command echoes back. This
+ * is the content-level backstop to isSensitivePath's path-level check: even
+ * when a secret arrives via stdin (`cat .env | mfn freq`) — where there is no
+ * path to vet — a JWT/private key/cloud token is replaced before it reaches
+ * stdout. Returns the (possibly) masked text and how many tokens were masked.
+ */
+export declare function redactSecrets(text: string): {
+    text: string;
+    redactedCount: number;
+};
+/**
+ * True for URLs that must never be probed: cloud metadata services. Local
+ * dev servers (localhost/127.0.0.1) stay allowed — probing them is the point.
+ */
+export declare function isBlockedUrl(url: URL): boolean;
+export declare const blockedUrlMessage: (url: string) => string;

package/bin/utility/index.d.ts

@@ -5,7 +5,7 @@ export declare function Logger(): {
     debug: (debug: string) => void;
 };
 export declare function CommandBuilder(instance: any): {
-    add: (alias: string, describe: string, builder: object, handler: (argv: any) => any) => void;
+    add: (alias: string, describe: string, builder: (yargs: any) => any, handler: (argv: any) => void | Promise<void>) => void;
 };
 /**
  * Get the current user's name based on the operating system.

package/bin/utility/suggest.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Rewrite yargs' "Unknown argument: X" into an agent-actionable message when X
+ * is the attempted command: name the problem correctly, suggest the nearest
+ * real command, and point at `mfn capabilities`.
+ */
+export declare function improveUnknownCommandMessage(msg: string): string;

package/llms.txt

@@ -1,58 +1,127 @@
 # @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.
+> 50 headless, JSON-first commands for AI agents and developers: extract instead
+> of dump (token savers), compute instead of guess (hallucination killers),
+> one-call system/code/network facts, and cross-platform OS actions (clipboard,
+> notifications, trash, processes). Every command behaves identically for a
+> human at a terminal and an agent reading stdout.
 
 ## Agent contract (read this first)
 
+- **Zero-install:** `npx -y @master4n/master-cli <command> --json` works without a
+  global install; with it installed, the binary is `mfn`.
 - **Discover commands:** `mfn capabilities --json` returns the full manifest
-  (`{ name, version, bin, conventions, commands:[{name,summary,examples}] }`).
+  (`{ name, version, bin, conventions, docs, categories, commands:[{name,category,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.
+- **Clean channels:** banners/spinners/logs go to **stderr**; **stdout carries only
+  the JSON result**, so `mfn <cmd> --json | jq` always works.
+- **No prompts in headless mode:** with `--json` or when piped, commands never block.
+- **Strict parsing:** unknown commands/flags and missing args → `{ok:false, error:"UsageError"}`, exit 2.
+- **Fast:** ~60ms per invocation; heavy/TTY-only deps load lazily.
+
+## Token savers (read less, extract exactly)
+
+- `mfn json [query] [-f file] [--keys] [--length] --json` — one value from JSON by
+  dot/bracket path (`scripts.build`, `users[0].name`); stdin or file. Don't read the document.
+- `mfn schema [query] [-f file] --json` — infer JSON shape (dot-paths → types, arrays
+  sampled). A 10MB payload becomes ~20 lines.
+- `mfn count [text] [-f file] --json` — lines/words/chars/bytes + `tokensEstimate`
+  (~4 chars/token heuristic). Know the cost before reading.
+- `mfn lines <file> [-s start] [-e end | -n count] --json` — exact 1-based line range,
+  capped at 2000 lines. Returns `totalLines` too.
+- `mfn outline <file> [-k kind] [-e] --json` — symbols + line numbers for
+  .ts/.tsx/.js/.jsx/.py/.go/.md. Pair with `lines` to read only what matters.
+- `mfn diff <a> <b> [-s] --json` — structured hunks `{aStart,aLines,bStart,bLines,removed,added}`;
+  `-s` for locations/counts only.
+- `mfn freq [file] [-t top] [-m min] --json` — most repeated lines (log triage in one call).
+- `mfn imports [file] | --who <module> --json` — a file's imports (grouped
+  relative/packages/builtin), or every file importing a module.
+- `mfn repo [-n commits] --json` — git branch, staged/unstaged/untracked counts,
+  ahead/behind, remotes, recent commits. Replaces 4-5 git calls.
+- `mfn sys --json` — OS, arch, node, CPU, memory, user, shell, timezone, cwd in one object.
+- `mfn have <tools...> --json` — which tools exist, their path + version, in one call.
+- `mfn size [dir] [-t top] --json` / `mfn ext [dir] --json` / `mfn recent [dir] [-t top] --json`
+  — disk usage, project composition by extension, newest files.
+- `mfn ports [--min N] --json` — ALL listening TCP ports with pid/command.
+- `mfn ip [-a] --json` — local interfaces/addresses; `primaryIPv4` convenience field.
+- `mfn pkg [name] --json` — declared vs installed dependency versions; `missing` list.
+- `mfn env [names...] [-p prefix] --json` — env vars; secret-looking values are
+  ALWAYS redacted; no names → name list only.
+- `mfn dotenv [-f .env] [-e .env.example] --json` — missing/extra keys; values never read.
+
+## Exact computation (never guess)
+
+- `mfn calc <expr> --json` — `+ - * / % ^` with parens; integer math in BigInt
+  (`2^53 + 1` → `9007199254740993`, exact). `exact:true|false` flag in output.
+- `mfn base <value> [-f hex|dec|bin|oct] --json` — 0xff/0b1010/0o755/decimal → all bases, BigInt-safe.
+- `mfn semver <versions...> [-b major|minor|patch] [-s] --json` — validate/compare/sort/bump
+  per semver.org (prerelease ordering correct).
+- `mfn cron <expr> [-n next] --json` — validate 5-field cron (+ @daily etc.), plain-English
+  description, next run times (local + ISO + epochMs).
+- `mfn regex <pattern> [text] [-f file] [--flags imsuvy] --json` — all matches with
+  line/index/groups. Test, don't assume.
+- `mfn url <value> --json` — components + decoded query params (repeats → arrays).
+- `mfn escape [text] [-a shell|json|regex|html|url|string] --json` — context-exact escaping.
+- `mfn case [text] [-t camel|snake|kebab|pascal|constant|dot|path|title|sentence|lower|upper] --json`
+  — identifier style conversion; omit `-t` for all styles.
+- `mfn epoch <value> --json` / `mfn epoch --from <date> --json` — epoch ↔ date
+  (unit auto-detected s/ms/µs/ns).
+- `mfn date [from] [--tz] [--format] --json` — date across timezones (IANA), defaults to now.
+- `mfn decode -t <jwt> --json` — JWT header+payload+expiry (signature NOT verified).
+
+## Actions (do, don't script)
+
+- `mfn replace <search> <replacement> -g <glob> [--write] --json` — literal find/replace
+  across files; DRY-RUN by default, `--write` to apply; per-file counts.
+- `mfn wait [-p port | -u url | -f file] [-t seconds] --json` — block until ready;
+  replaces sleep-and-retry loops. Exit 1 on timeout.
+- `mfn kill -p <ports...> [-y] --json` — kill listeners on ports (headless: needs explicit -p).
+- `mfn http <url> [-m GET|HEAD] [-H "Name: value"] --json` — status/headers/timing
+  + body preview capped at 2KB (never a full dump). Exit 1 on non-2xx.
+- `mfn port [-c port | -n count] --json` — find free port(s) / check one.
+- `mfn id [-t uuid|uuid7|nano] [-n count] --json` — UUID v4, time-ordered v7 (RFC 9562), nano.
+- `mfn hash [text] [-a md5|sha1|sha256|sha512] [-f file] --json` — digest of string/file/stdin.
+- `mfn encode [text] [--as base64|base64url|hex|url] [-d] --json` — encode/decode (strict charset).
+- `mfn random [-b bytes] | [-p [-l length]] --json` — CSPRNG bytes / unbiased password.
+- `mfn sc [pattern] [--depth] [--limit] --json` — fuzzy file find under cwd.
+- `mfn cts [--type text|svg|png|jpeg] --json` — directory tree.
+- `mfn update [package] --json` — global npm update of the CLI (or named package).
+
+## OS-level (cross-platform: macOS / Windows / Linux)
+
+- `mfn clip [text] [-r] --json` — read/write the system clipboard. Write via arg or
+  stdin (`git diff | mfn clip`); read returns `{chars, text}`. Headless sessions fail
+  cleanly with `ClipboardUnavailable`.
+- `mfn notify <message> [-t title] --json` — desktop notification (osascript /
+  notify-send / WinRT toast). Ping the user when a long task finishes.
+- `mfn open <target> --json` — open an http(s) URL or existing file in the default
+  app/browser. Non-http schemes and missing paths are rejected (exit 2).
+- `mfn procs [pattern] [-t top] --json` — search processes by name: pid/cpu/memMB,
+  sorted by cpu. One call instead of ps|grep (or tasklist parsing).
+- `mfn disk [-a] --json` — per-mount totals/free/used% (df -kP / Win32_LogicalDisk).
+- `mfn trash <paths...> --json` — move to the OS trash (reversible; ~/.Trash, XDG
+  spec, Recycle Bin). Refuses root/home/cwd and parents of cwd. Use instead of rm.
+- `mfn dns <hostname> [-t a|aaaa|cname|mx|txt|ns] --json` — system resolver +
+  record sweep; missing record types are null, not errors.
+
+## Guardrails (always on — there are no bypass flags)
+
+- File-content commands (`lines` `json` `schema` `diff` `freq` `regex -f`) refuse
+  credential/secret paths (`~/.ssh`, `.env*`, `*.pem`, `.npmrc`, …) → `SensitivePath`, exit 2.
+- `clip` read redacts secret-shaped content (keys/JWTs/tokens) → `redacted:true`.
+- `env` redacts by name AND value shape; `dotenv` never reads values at all.
+- `http`/`wait -u` refuse cloud metadata endpoints (169.254.169.254 etc.) → `BlockedTarget`;
+  `http` redacts `set-cookie` response headers.
+- `open` allows only http(s)/existing paths; `trash` is reversible and refuses
+  root/home/cwd; `kill` validates ports and PIDs; `replace` is dry-run unless `--write`.
+- Full threat model: SECURITY.md (shipped in this package).
 
 ## 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.
+- Time/date powered by `@master4n/temporal-transformer` v2 (Luxon-backed, integer epochs).
+- Zero shell interpolation: every subprocess uses `execFile` (no shell) — inputs cannot
+  inject commands. See SECURITY.md (shipped in this package) for the full threat model.
+- `count.tokensEstimate` is a ~4-chars/token heuristic, not a model tokenizer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@master4n/master-cli",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "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",
   "repository": {
@@ -21,6 +21,10 @@
     "ai-agents",
     "agent-tools",
     "llm-tools",
+    "llms-txt",
+    "agent-friendly",
+    "claude-code",
+    "coding-agent",
     "automation",
     "headless",
     "json-output",