shell-aliasforge 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { applyToRc, rcPathFor } from "./apply/apply.js";
+import { selectSuggestions } from "./apply/select.js";
+import { UsageError } from "./errors.js";
+import { createEnvironment } from "./analyze/environment.js";
+import { renderJson, renderReport } from "./analyze/report.js";
+import { computeStats, renderStats } from "./analyze/stats.js";
+import { suggest } from "./analyze/suggest.js";
+import { loadHistory } from "./history/index.js";
+import { scanHistory } from "./risks/engine.js";
+import { renderRisks, renderRisksJson } from "./risks/report.js";
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const SHELLS = ["bash", "zsh", "fish"];
+const HELP = `aliasforge ${VERSION}
+
+Usage: aliasforge <command> [options]
+
+Commands:
+  suggest   Suggest aliases from shell history
+  risks     Flag dangerous commands and leaked secrets
+  apply     Write chosen aliases to a managed block in your rc file
+  stats     Show history size, top commands and time span
+
+suggest options:
+  --shell bash|zsh|fish   Shell dialect (default: from --file or $SHELL)
+  --file <path>           Read this history file instead of the default
+  --min-count N           Minimum occurrences (default 5)
+  --min-length N          Minimum command length in characters (default 8)
+  --top N                 Number of suggestions (default 10)
+  --json                  Machine-readable output
+
+risks options:
+  --shell, --file, --json as above
+
+stats options:
+  --shell, --file, --json as above, plus --top N (default 10)
+
+apply options:
+  --shell bash|zsh|fish   Required. Which rc file to update
+  --select 1,3,gs         Ranks or names from suggest (default: all suggestions)
+  --dry-run               Print a diff and write nothing
+  --file, --min-count, --min-length, --top as for suggest
+
+apply writes only between "# >>> aliasforge >>>" and "# <<< aliasforge <<<",
+keeps definitions already in the block, and makes a timestamped backup first.
+`;
+function defaultIo() {
+    return {
+        out: (text) => console.log(text),
+        err: (text) => console.error(text),
+        home: homedir(),
+        env: process.env,
+    };
+}
+function positiveInt(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new UsageError(`${name} must be a positive integer`);
+    return parsed;
+}
+function parseShell(value) {
+    if (value === undefined)
+        return undefined;
+    if (!SHELLS.includes(value))
+        throw new UsageError("--shell must be bash, zsh or fish");
+    return value;
+}
+function shellFromEnv(env) {
+    const name = basename(env.SHELL ?? "");
+    return SHELLS.find((shell) => shell === name) ?? "bash";
+}
+function loadFromOptions(requested, file, io) {
+    const shell = parseShell(requested);
+    const shellHint = shell ?? (file === undefined ? shellFromEnv(io.env) : undefined);
+    return loadHistory({ file, shell: shellHint, home: io.home });
+}
+function runSuggest(args, io) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            shell: { type: "string" },
+            file: { type: "string" },
+            "min-count": { type: "string" },
+            "min-length": { type: "string" },
+            top: { type: "string" },
+            json: { type: "boolean" },
+        },
+        strict: true,
+    });
+    const options = {
+        minCount: positiveInt("--min-count", values["min-count"], 5),
+        minLength: positiveInt("--min-length", values["min-length"], 8),
+        top: positiveInt("--top", values.top, 10),
+    };
+    const history = loadFromOptions(values.shell, values.file, io);
+    const isTaken = createEnvironment({ shell: history.shell, home: io.home, path: io.env.PATH ?? "" });
+    const suggestions = suggest(history.entries, isTaken, { ...options, shell: history.shell });
+    io.out(values.json
+        ? renderJson({ shell: history.shell, historyEntries: history.entries.length, suggestions })
+        : renderReport(history.shell, suggestions));
+    return 0;
+}
+function runRisks(args, io) {
+    const { values } = parseArgs({
+        args,
+        options: { shell: { type: "string" }, file: { type: "string" }, json: { type: "boolean" } },
+        strict: true,
+    });
+    const history = loadFromOptions(values.shell, values.file, io);
+    const findings = scanHistory(history.entries);
+    io.out(values.json
+        ? renderRisksJson({ shell: history.shell, historyEntries: history.entries.length, findings })
+        : renderRisks(findings, history.entries.length));
+    return 0;
+}
+function describeApply(result, dryRun) {
+    const names = (status) => result.changes.filter((c) => c.status === status).map((c) => c.name).join(", ");
+    const lines = [`Target: ${result.rcPath}`];
+    if (names("added"))
+        lines.push(`Added: ${names("added")}`);
+    if (names("unchanged"))
+        lines.push(`Already present: ${names("unchanged")}`);
+    if (result.skipped.length > 0)
+        lines.push(`Skipped (every proposed name clashes): ${result.skipped.join("; ")}`);
+    if (result.diff === "") {
+        lines.push("Nothing to change.");
+    }
+    else if (dryRun) {
+        lines.push("", result.diff, "", "Dry run: nothing was written.");
+    }
+    else {
+        lines.push(result.backupPath ? `Backup: ${result.backupPath}` : "No backup needed: the file did not exist.");
+        lines.push("Open a new shell or source the file to use the new definitions.");
+    }
+    return lines.join("\n");
+}
+function runApply(args, io) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            shell: { type: "string" },
+            file: { type: "string" },
+            select: { type: "string" },
+            "dry-run": { type: "boolean" },
+            "min-count": { type: "string" },
+            "min-length": { type: "string" },
+            top: { type: "string" },
+        },
+        strict: true,
+    });
+    if (values.shell === undefined)
+        throw new UsageError("apply needs --shell bash|zsh|fish (it decides which rc file is edited)");
+    const options = {
+        minCount: positiveInt("--min-count", values["min-count"], 5),
+        minLength: positiveInt("--min-length", values["min-length"], 8),
+        top: positiveInt("--top", values.top, 10),
+    };
+    const history = loadFromOptions(values.shell, values.file, io);
+    const isTaken = createEnvironment({ shell: history.shell, home: io.home, path: io.env.PATH ?? "" });
+    const suggestions = suggest(history.entries, isTaken, { ...options, shell: history.shell });
+    const selected = selectSuggestions(suggestions, values.select);
+    const dryRun = values["dry-run"] === true;
+    const result = applyToRc({
+        shell: history.shell,
+        rcPath: rcPathFor(history.shell, io.home, io.env),
+        selected,
+        explicitNames: values.select !== undefined,
+        dryRun,
+        now: new Date(),
+    });
+    io.out(selected.length === 0 ? "No alias suggestions to apply." : describeApply(result, dryRun));
+    return 0;
+}
+function runStats(args, io) {
+    const { values } = parseArgs({
+        args,
+        options: { shell: { type: "string" }, file: { type: "string" }, top: { type: "string" }, json: { type: "boolean" } },
+        strict: true,
+    });
+    const top = positiveInt("--top", values.top, 10);
+    const history = loadFromOptions(values.shell, values.file, io);
+    const stats = computeStats(history.entries, top);
+    io.out(values.json ? JSON.stringify({ shell: history.shell, ...stats }, null, 2) : renderStats(history.shell, stats));
+    return 0;
+}
+function isUsageError(error) {
+    const code = error.code ?? "";
+    return error instanceof UsageError || code.startsWith("ERR_PARSE_ARGS");
+}
+function dispatch(command, rest, io) {
+    if (command === "suggest")
+        return runSuggest(rest, io);
+    if (command === "risks")
+        return runRisks(rest, io);
+    if (command === "apply")
+        return runApply(rest, io);
+    if (command === "stats")
+        return runStats(rest, io);
+    io.err(`Unknown command: ${command}\n\n${HELP}`);
+    return 2;
+}
+export function run(args, io = defaultIo()) {
+    const [command, ...rest] = args;
+    if (command === "--version" || command === "-v") {
+        io.out(VERSION);
+        return 0;
+    }
+    if (command === undefined || command === "--help" || command === "-h") {
+        io.out(HELP);
+        return 0;
+    }
+    try {
+        return dispatch(command, rest, io);
+    }
+    catch (error) {
+        io.err(error instanceof Error ? error.message : String(error));
+        return isUsageError(error) ? 2 : 1;
+    }
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = run(process.argv.slice(2));
+}

package/dist/errors.js

@@ -0,0 +1,3 @@
+/** Bad command-line input. The CLI reports it with exit code 2. */
+export class UsageError extends Error {
+}

package/dist/history/bash.js

@@ -0,0 +1,22 @@
+import { splitLines, toText } from "./text.js";
+const TIMESTAMP_LINE = /^#(\d{9,11})$/;
+/**
+ * Parse ~/.bash_history. One command per line; with HISTTIMEFORMAT set,
+ * a `#<epoch>` line precedes each command.
+ */
+export function parseBash(input) {
+    const entries = [];
+    let pending;
+    for (const line of splitLines(toText(input))) {
+        const stamp = TIMESTAMP_LINE.exec(line);
+        if (stamp) {
+            pending = Number(stamp[1]);
+            continue;
+        }
+        if (line.trim() === "")
+            continue;
+        entries.push(pending === undefined ? { command: line } : { command: line, timestamp: pending });
+        pending = undefined;
+    }
+    return entries;
+}

package/dist/history/detect.js

@@ -0,0 +1,36 @@
+import { basename, join } from "node:path";
+import { splitLines, toText } from "./text.js";
+const SNIFF_LINES = 50;
+export function defaultHistoryPath(shell, home) {
+    switch (shell) {
+        case "bash":
+            return join(home, ".bash_history");
+        case "zsh":
+            return join(home, ".zsh_history");
+        case "fish":
+            return join(home, ".local", "share", "fish", "fish_history");
+    }
+}
+function shellFromName(path) {
+    const name = basename(path).toLowerCase();
+    if (name.includes("fish"))
+        return "fish";
+    if (name.includes("zsh"))
+        return "zsh";
+    if (name.includes("bash"))
+        return "bash";
+    return undefined;
+}
+function shellFromContent(input) {
+    const head = input instanceof Uint8Array ? input.subarray(0, 64 * 1024) : input.slice(0, 64 * 1024);
+    const lines = splitLines(toText(head)).slice(0, SNIFF_LINES);
+    if (lines.some((line) => line.startsWith("- cmd:")))
+        return "fish";
+    if (lines.some((line) => /^: \d+:\d+;/.test(line)))
+        return "zsh";
+    return "bash";
+}
+/** Guess the shell from the file name first, then from the content. */
+export function detectShell(path, input) {
+    return shellFromName(path) ?? shellFromContent(input);
+}

package/dist/history/fish.js

@@ -0,0 +1,29 @@
+import { splitLines, toText } from "./text.js";
+const CMD_LINE = /^- cmd: ?(.*)$/;
+const WHEN_LINE = /^ {2}when: *(\d+)\s*$/;
+/** Fish escapes backslash and newline inside `cmd:` values. */
+function unescapeFish(value) {
+    return value.replace(/\\(.)/g, (_match, char) => (char === "n" ? "\n" : char));
+}
+/**
+ * Parse fish_history: YAML-like entries (`- cmd: ...` then `  when: ...`).
+ * Other keys such as `paths:` are ignored.
+ */
+export function parseFish(input) {
+    const entries = [];
+    let current;
+    for (const line of splitLines(toText(input))) {
+        const cmd = CMD_LINE.exec(line);
+        if (cmd) {
+            const command = unescapeFish(cmd[1]);
+            current = { command };
+            if (command.trim() !== "")
+                entries.push(current);
+            continue;
+        }
+        const when = WHEN_LINE.exec(line);
+        if (when && current)
+            current.timestamp = Number(when[1]);
+    }
+    return entries;
+}

package/dist/history/index.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { parseBash } from "./bash.js";
+import { defaultHistoryPath, detectShell } from "./detect.js";
+import { parseFish } from "./fish.js";
+import { parseZsh } from "./zsh.js";
+export { defaultHistoryPath, detectShell } from "./detect.js";
+export { parseBash, parseFish, parseZsh };
+export function parseHistory(shell, input) {
+    switch (shell) {
+        case "bash":
+            return parseBash(input);
+        case "zsh":
+            return parseZsh(input);
+        case "fish":
+            return parseFish(input);
+    }
+}
+/** Read and parse a history file. Never executes anything from it. */
+export function loadHistory(options) {
+    const file = options.file ?? defaultHistoryPath(options.shell ?? "bash", options.home);
+    const bytes = readFileSync(file);
+    const shell = options.shell ?? detectShell(file, bytes);
+    return { shell, file, entries: parseHistory(shell, bytes) };
+}

package/dist/history/text.js

@@ -0,0 +1,13 @@
+const decoder = new TextDecoder("utf-8");
+/** Decode bytes as UTF-8 (invalid bytes become U+FFFD) and drop a leading BOM. */
+export function toText(input) {
+    const text = typeof input === "string" ? input : decoder.decode(input);
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/** Split on LF or CRLF. A trailing newline does not produce an empty last line. */
+export function splitLines(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}

package/dist/history/types.js

@@ -0,0 +1 @@
+export {};

package/dist/history/zsh.js

@@ -0,0 +1,62 @@
+import { splitLines, toText } from "./text.js";
+const META = 0x83;
+const EXTENDED_LINE = /^: (\d+):\d+;(.*)$/;
+/**
+ * Zsh stores bytes 0x00 and 0x83-0x9f as a Meta byte (0x83) followed by
+ * the original byte XOR 0x20. Undo that before decoding as UTF-8.
+ */
+export function unmetafy(bytes) {
+    const out = new Uint8Array(bytes.length);
+    let length = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        const byte = bytes[i];
+        if (byte === META) {
+            i++;
+            if (i < bytes.length)
+                out[length++] = bytes[i] ^ 0x20;
+        }
+        else {
+            out[length++] = byte;
+        }
+    }
+    return out.subarray(0, length);
+}
+/**
+ * Parse ~/.zsh_history, plain or extended (`: 1700000000:0;command`).
+ * A line ending in a backslash continues on the next line.
+ */
+export function parseZsh(input) {
+    const text = toText(typeof input === "string" ? input : unmetafy(input));
+    const entries = [];
+    let parts = [];
+    let timestamp;
+    const flush = () => {
+        const command = parts.join("\n");
+        if (command.trim() !== "") {
+            entries.push(timestamp === undefined ? { command } : { command, timestamp });
+        }
+        parts = [];
+        timestamp = undefined;
+    };
+    for (const line of splitLines(text)) {
+        if (parts.length === 0) {
+            const extended = EXTENDED_LINE.exec(line);
+            if (extended)
+                timestamp = Number(extended[1]);
+            parts.push(extended ? extended[2] : line);
+        }
+        else {
+            parts.push(line);
+        }
+        const last = parts[parts.length - 1];
+        if (last.endsWith("\\")) {
+            parts[parts.length - 1] = last.slice(0, -1);
+        }
+        else {
+            flush();
+        }
+    }
+    if (parts.length > 0)
+        flush();
+    return entries;
+}

package/dist/risks/engine.js

@@ -0,0 +1,76 @@
+import { normalizeCommand } from "../analyze/normalize.js";
+import { maskRanges, shorten } from "./mask.js";
+import { packs as defaultPacks } from "./packs/index.js";
+/** Longer command lines are scanned only up to this many characters. */
+const MAX_SCAN_LENGTH = 10_000;
+function compile(pattern) {
+    const flags = [...new Set(`${pattern.flags ?? ""}gd`)].join("");
+    return { pattern, regex: new RegExp(pattern.pattern, flags) };
+}
+function overlaps(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+function secretRange(match) {
+    const group = match.indices?.groups?.secret;
+    return group ? { start: group[0], end: group[1] } : { start: match.index, end: match.index + match[0].length };
+}
+/** Secret matches in rule order. A later match overlapping an earlier one is dropped. */
+function findSecrets(text, rules) {
+    const hits = [];
+    for (const { pattern, regex } of rules) {
+        for (const match of text.matchAll(regex)) {
+            const range = secretRange(match);
+            if (range.end > range.start && !hits.some((hit) => overlaps(hit.range, range))) {
+                hits.push({ pattern, range });
+            }
+        }
+    }
+    return hits;
+}
+function isoDate(timestamp) {
+    if (timestamp === undefined)
+        return undefined;
+    const date = new Date(timestamp * 1000);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
+}
+function toFinding(pattern, entry, timestamp, preview) {
+    const finding = {
+        id: pattern.id,
+        category: pattern.category,
+        severity: pattern.severity,
+        title: pattern.title,
+        advice: pattern.advice,
+        entry,
+        preview,
+    };
+    const date = isoDate(timestamp);
+    return date === undefined ? finding : { ...finding, date };
+}
+function hasMatch(text, rule) {
+    rule.regex.lastIndex = 0;
+    return rule.regex.test(text);
+}
+/**
+ * Scan history entries for dangerous commands and secrets. Pure text matching:
+ * nothing from history is ever executed. Every preview has secrets masked.
+ */
+export function scanHistory(entries, packList = defaultPacks) {
+    const rules = packList.flatMap((pack) => pack.patterns).map(compile);
+    const secretRules = rules.filter((rule) => rule.pattern.category === "secret");
+    const dangerRules = rules.filter((rule) => rule.pattern.category === "danger");
+    const findings = [];
+    entries.forEach((entry, index) => {
+        const text = normalizeCommand(entry.command).slice(0, MAX_SCAN_LENGTH);
+        if (text === "")
+            return;
+        const secrets = findSecrets(text, secretRules);
+        const preview = shorten(maskRanges(text, secrets.map((hit) => hit.range)));
+        const matched = [
+            ...secrets.map((hit) => hit.pattern),
+            ...dangerRules.filter((rule) => hasMatch(text, rule)).map((rule) => rule.pattern),
+        ];
+        for (const pattern of matched)
+            findings.push(toFinding(pattern, index + 1, entry.timestamp, preview));
+    });
+    return findings;
+}

package/dist/risks/mask.js

@@ -0,0 +1,23 @@
+const PREVIEW_LENGTH = 100;
+/**
+ * Keep up to the first 4 characters and hide the rest. Short secrets show
+ * fewer characters (a quarter of their length) so they are never exposed.
+ */
+export function maskSecret(secret) {
+    const visible = Math.min(4, Math.floor(secret.length / 4));
+    return `${secret.slice(0, visible)}****`;
+}
+/** Replace each range of `text` with its masked form. Ranges must not overlap. */
+export function maskRanges(text, ranges) {
+    const ordered = [...ranges].sort((a, b) => a.start - b.start);
+    let result = "";
+    let cursor = 0;
+    for (const range of ordered) {
+        result += text.slice(cursor, range.start) + maskSecret(text.slice(range.start, range.end));
+        cursor = range.end;
+    }
+    return result + text.slice(cursor);
+}
+export function shorten(text, length = PREVIEW_LENGTH) {
+    return text.length <= length ? text : `${text.slice(0, length)}…`;
+}

package/dist/risks/packs/cloud.js

@@ -0,0 +1,60 @@
+const R = String.raw;
+export const cloud = [
+    {
+        id: "cloud/aws-access-key-id",
+        category: "secret",
+        severity: "high",
+        title: "AWS access key ID",
+        advice: "Deactivate the key in IAM, create a new one and remove this entry from your history.",
+        pattern: R `\b(?<secret>(?:AKIA|ASIA)[A-Z0-9]{16})\b`,
+    },
+    {
+        id: "cloud/aws-secret-assignment",
+        category: "secret",
+        severity: "high",
+        title: "AWS secret or session token",
+        advice: "Rotate the credential in IAM and remove this entry from your history.",
+        pattern: R `\bAWS_(?:SECRET_ACCESS_KEY|SESSION_TOKEN)=["']?(?<secret>[^\s"'$][^\s"']*)`,
+    },
+    {
+        id: "cloud/aws-configure-set",
+        category: "secret",
+        severity: "high",
+        title: "AWS credential set through aws configure",
+        advice: "Rotate the credential in IAM and remove this entry from your history.",
+        pattern: R `\baws\s+configure\s+set\s+\w*(?:secret_access_key|session_token)\s+["']?(?<secret>[^\s"']+)`,
+        flags: "i",
+    },
+    {
+        id: "cloud/google-api-key",
+        category: "secret",
+        severity: "high",
+        title: "Google API key",
+        advice: "Delete or restrict the key in the Cloud console and remove this entry from your history.",
+        pattern: R `\b(?<secret>AIza[0-9A-Za-z_-]{35})`,
+    },
+    {
+        id: "cloud/s3-recursive-delete",
+        category: "danger",
+        severity: "medium",
+        title: "aws s3 rm --recursive or rb --force",
+        advice: "Run with --dryrun first and check the bucket and prefix.",
+        pattern: R `\baws\s+s3\s+(?:rm\b[^;&|]*\s--recursive|rb\b[^;&|]*\s--force)(?=\s|$)`,
+    },
+    {
+        id: "cloud/terraform-auto-destroy",
+        category: "danger",
+        severity: "high",
+        title: "terraform destroy without confirmation",
+        advice: "Review the plan (terraform plan -destroy) and confirm the workspace first.",
+        pattern: R `\bterraform\s+destroy\b[^;&|]*\s-auto-approve(?=\s|$)`,
+    },
+    {
+        id: "cloud/gcloud-project-delete",
+        category: "danger",
+        severity: "high",
+        title: "gcloud projects delete",
+        advice: "Deleting a project removes all its resources. Confirm the project ID.",
+        pattern: R `\bgcloud\s+projects\s+delete\b`,
+    },
+];