promptpilot 0.1.3 → 0.1.5

package/README.md

@@ -48,6 +48,26 @@ Install from npm:
 npm install -g promptpilot
 ```
 
+Run `promptpilot` with no arguments in an interactive terminal to open the CLI welcome screen:
+
+```text
+ PromptPilot  v0.1.x
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ Welcome back                                                                │
+│                                                                              │
+│       .-''''-.                          Launchpad                            │
+│     .'  .--.  '.                       Run promptpilot optimize "..."        │
+│    /   / oo \   \                      Pipe directly into Claude with | claude│
+│   |    \_==_/    |                                                         │
+│    \  \_/  \_/  /                      Custom local model                    │
+│     '._/|__|\_.'                       Use --model promptpilot-compressor    │
+│                                                                              │
+│ /Users/you/project                     Commands                              │
+│                                        optimize  optimize and route prompts  │
+│                                        --help    show the full CLI reference │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
 Install one or two small Ollama models so the local router has options:
 
 ```bash

package/dist/cli.d.ts

@@ -3,6 +3,8 @@ import { createOptimizer } from './index.js';
 
 type CliWriter = {
     write(message: string): void;
+    isTTY?: boolean;
+    columns?: number;
 };
 interface CliIO {
     stdout: CliWriter;
@@ -12,6 +14,13 @@ interface CliIO {
 interface CliDependencies {
     createOptimizer: typeof createOptimizer;
     readStdin: (stdin?: NodeJS.ReadStream) => Promise<string>;
+    getCliInfo?: (stdout: CliWriter) => {
+        cwd: string;
+        version: string;
+        color: boolean;
+        columns?: number;
+        user?: string;
+    };
 }
 declare function runCli(argv: string[], io?: CliIO, dependencies?: CliDependencies): Promise<number>;
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { realpathSync } from "fs";
+import { readFileSync, realpathSync } from "fs";
 import { fileURLToPath } from "url";
 
 // src/errors.ts
@@ -360,13 +360,13 @@ var modeGuidance = {
   clarity: "Improve clarity, remove ambiguity, and keep the request easy for a downstream model to follow.",
   concise: "Minimize token count while preserving user intent, constraints, and expected output.",
   detailed: "Make the request explicit and complete, including structure and success criteria.",
-  structured: "Organize the request into clean sections with compact headings and bullet points where helpful.",
+  structured: "Organize the request into sections only when that improves clarity or token efficiency.",
   persuasive: "Refine wording so the request is compelling and likely to elicit a thoughtful response.",
   compress: "Aggressively compress redundant wording while preserving the meaning and critical constraints.",
   claude_cli: "Optimize specifically for Claude CLI: compact sections, direct instructions, and minimal boilerplate."
 };
 var presetGuidance = {
-  code: "Favor precise technical requirements, edge cases, and expected output format for code tasks.",
+  code: "Favor precise technical requirements, edge cases, expected output format, and a compact inspect-plan-act-test-reflect loop for code tasks.",
   email: "Preserve the sender's goal, tone, and audience; aim for a realistic and usable writing request.",
   essay: "Preserve thesis, structure, and voice guidance while making the prompt clearer.",
   support: "Favor concise issue context, user impact, and desired resolution details.",
@@ -384,6 +384,10 @@ function getOptimizationSystemPrompt(mode, preset) {
     "- Preserve critical constraints and task goals.",
     "- Improve clarity, structure, and downstream usefulness.",
     "- Keep the result compact when the mode requests compression.",
+    "- Do not force sections when direct phrasing is shorter and equally clear.",
+    "- Remove redundancy aggressively when the source prompt repeats the same goal multiple ways.",
+    "- For code tasks, prefer a terse agent brief over narrative prose.",
+    "- For code tasks, structure the prompt around a Karpathy-style loop: inspect, plan, act, test, reflect, repeat.",
     `Mode guidance: ${modeGuidance[mode]}`,
     preset ? `Preset guidance: ${presetGuidance[preset]}` : "Preset guidance: none"
   ].join("\n");
@@ -712,7 +716,11 @@ function tokenize(value) {
   );
 }
 function extractConstraints(value) {
-  return value.split(/\n+/).map((line) => line.trim()).filter((line) => /(must|should|avoid|do not|don't|never|exactly|at most|under|limit|max)/i.test(line)).slice(0, 8);
+  return Array.from(
+    new Set(
+      value.split(/\n+/).flatMap((line) => line.split(/(?<=[.!?])\s+/)).map((line) => line.trim().replace(/^[-*]\s*/, "")).filter((line) => line.length > 0 && line.length <= 180).filter((line) => /(must|should|avoid|do not|don't|never|exactly|at most|under|limit|max|preserve|keep)/i.test(line))
+    )
+  ).slice(0, 8);
 }
 function extractEntities(value) {
   return Array.from(
@@ -907,6 +915,7 @@ var PromptOptimizer = class {
     );
     let provider = input.bypassOptimization ? "heuristic" : this.config.provider ?? DEFAULT_PROVIDER;
     let model = provider === "ollama" ? this.config.ollamaModel ?? "auto" : "heuristic";
+    let usedPreprocessedFallback = false;
     let optimizedPrompt = originalPrompt;
     let providerWarnings = [];
     let providerChanges = [];
@@ -941,6 +950,11 @@ var PromptOptimizer = class {
         optimizedPrompt = ollamaResult.optimizedPrompt;
         providerWarnings = ollamaResult.warnings;
         providerChanges = ollamaResult.changes;
+        if (ollamaResult.source === "preprocessed") {
+          provider = "heuristic";
+          model = "cheap-preprocess";
+          usedPreprocessedFallback = true;
+        }
       } else if (provider === "ollama") {
         provider = "heuristic";
         model = "heuristic";
@@ -949,7 +963,7 @@ var PromptOptimizer = class {
         ];
       }
     }
-    if (provider === "heuristic") {
+    if (provider === "heuristic" && !usedPreprocessedFallback) {
       const fallback = this.heuristicOptimize({
         input: {
           ...input,
@@ -1081,29 +1095,88 @@ var PromptOptimizer = class {
     });
   }
   async tryOllamaOptimization(options) {
+    const preprocessedPrompt = cheapCompress(options.input.prompt);
+    const preprocessedTokenCount = this.estimator.estimateText(preprocessedPrompt);
+    const ultraMode = preprocessedTokenCount > 500;
     try {
       if (!await this.client.isAvailable()) {
-        return null;
+        return {
+          optimizedPrompt: preprocessedPrompt,
+          changes: ["Applied cheap local preprocessing because Ollama was unavailable."],
+          warnings: ["Ollama was unavailable, so PromptPilot kept the cheap preprocessed prompt."],
+          source: "preprocessed"
+        };
+      }
+      const systemPrompt = ultraMode ? `${getOptimizationSystemPrompt(options.input.mode, options.input.preset)}
+Mode: Ultra compression. Minimize tokens aggressively.` : getOptimizationSystemPrompt(options.input.mode, options.input.preset);
+      const optimizationPrompt = buildOptimizationPrompt(
+        {
+          ...options.input,
+          prompt: preprocessedPrompt
+        },
+        options.relevantContext,
+        options.extractedConstraints
+      );
+      const timeoutMs = options.input.timeoutMs ?? this.config.timeoutMs;
+      let optimizedPrompt = "";
+      let responseChanges = [];
+      let responseWarnings = [];
+      try {
+        const response = await this.client.generateJson({
+          systemPrompt,
+          prompt: optimizationPrompt,
+          timeoutMs,
+          model: options.model,
+          temperature: this.config.temperature,
+          format: "json"
+        });
+        optimizedPrompt = normalizeWhitespace(response.optimizedPrompt ?? "");
+        responseChanges = response.changes ?? [];
+        responseWarnings = response.warnings ?? [];
+      } catch {
+        const raw = await this.client.generate({
+          systemPrompt,
+          prompt: optimizationPrompt,
+          timeoutMs,
+          model: options.model,
+          temperature: this.config.temperature
+        });
+        optimizedPrompt = sanitizeTextOptimizationOutput(raw);
+        responseChanges = [`Applied text-only Ollama optimization with ${options.model}.`];
       }
-      const response = await this.client.generateJson({
-        systemPrompt: getOptimizationSystemPrompt(options.input.mode, options.input.preset),
-        prompt: buildOptimizationPrompt(options.input, options.relevantContext, options.extractedConstraints),
-        timeoutMs: options.input.timeoutMs ?? this.config.timeoutMs,
-        model: options.model,
-        temperature: this.config.temperature,
-        format: "json"
-      });
-      const optimizedPrompt = normalizeWhitespace(response.optimizedPrompt ?? "");
       if (!optimizedPrompt) {
-        return null;
+        return {
+          optimizedPrompt: preprocessedPrompt,
+          changes: ["Applied cheap local preprocessing because the model returned an empty optimization."],
+          warnings: ["The local optimizer returned an empty result, so PromptPilot kept the preprocessed prompt."],
+          source: "preprocessed"
+        };
+      }
+      const optimizedTokenCount = this.estimator.estimateText(optimizedPrompt);
+      if (isCompressionSensitiveMode(options.input.mode) && optimizedTokenCount >= preprocessedTokenCount) {
+        return {
+          optimizedPrompt: preprocessedPrompt,
+          changes: [
+            ...responseChanges,
+            "Kept the cheap preprocessed prompt because the model output was not smaller."
+          ],
+          warnings: responseWarnings,
+          source: "preprocessed"
+        };
       }
       return {
         optimizedPrompt,
-        changes: response.changes ?? [`Applied Ollama optimization with ${options.model}.`],
-        warnings: response.warnings ?? []
+        changes: responseChanges.length > 0 ? responseChanges : [`Applied Ollama optimization with ${options.model}.`],
+        warnings: responseWarnings,
+        source: "ollama"
       };
     } catch {
-      return null;
+      return {
+        optimizedPrompt: preprocessedPrompt,
+        changes: ["Applied cheap local preprocessing because Ollama optimization failed."],
+        warnings: ["Ollama optimization failed, so PromptPilot kept the preprocessed prompt."],
+        source: "preprocessed"
+      };
     }
   }
   async resolveOllamaModel(options) {
@@ -1406,16 +1479,14 @@ var PromptOptimizer = class {
     }
   }
   heuristicOptimize(options) {
-    const lines = [
-      `Request: ${options.input.prompt}`,
-      options.input.task ? `Task type: ${options.input.task}` : "",
-      options.input.tone ? `Tone: ${options.input.tone}` : "",
-      options.input.outputFormat ? `Output format: ${options.input.outputFormat}` : "",
-      options.input.maxLength ? `Maximum length: ${options.input.maxLength}` : "",
-      options.constraints.length ? `Critical constraints: ${options.constraints.join("; ")}` : ""
-    ].filter(Boolean);
+    const isCodeRequest = isCodeFirstRequest(options.input);
+    const lines = isCodeRequest ? buildCodeFirstHeuristicPrompt(options.input, options.constraints) : buildGeneralHeuristicPrompt(options.input, options.constraints);
     const optimizedPrompt = lines.join("\n");
-    const changes = ["Normalized prompt structure for downstream model consumption."];
+    const changes = isCodeRequest ? [
+      "Compressed the prompt into a code-agent brief.",
+      "Removed redundant narrative phrasing.",
+      "Applied a Karpathy-style inspect-plan-act-test-reflect loop."
+    ] : ["Normalized prompt structure for downstream model consumption."];
     if (options.input.mode === "compress" || options.input.mode === "concise") {
       changes.push("Applied concise formatting to reduce token usage.");
     }
@@ -1496,6 +1567,14 @@ ${contextBlock}`);
   if (constraints.length > 0) {
     sections.push(`Constraints:
 - ${constraints.join("\n- ")}`);
+  }
+  if (isCodeFirstRequest(input.input)) {
+    sections.push(`Execution loop:
+- Inspect the relevant files and current behavior.
+- Plan the smallest safe next step.
+- Act with minimal, reversible changes.
+- Test or validate the result.
+- Reflect on gaps or risks, then repeat.`);
   }
   const desiredOutput = [
     input.routingDecision.selectedTarget ? `Selected target: ${formatTargetLabel(input.routingDecision.selectedTarget)}` : input.input.targetModel ? `Target model: ${input.input.targetModel}` : "Target model: claude",
@@ -1595,16 +1674,289 @@ function describeDownstreamTarget(target) {
 function formatTargetLabel(target) {
   return target.label ?? `${target.provider}:${target.model}`;
 }
+function isCompressionSensitiveMode(mode) {
+  return mode === "compress" || mode === "concise" || mode === "claude_cli";
+}
+function cheapCompress(text) {
+  return normalizeWhitespace(text).replace(/\b(?:please|kindly|just)\b/gi, "").replace(/\bI\s+(?:want|need|would\s+like\s+to)\b/gi, "").replace(/\s+([,.;:!?])/g, "$1").replace(/\s{2,}/g, " ").trim();
+}
+function sanitizeTextOptimizationOutput(raw) {
+  const normalized = normalizeWhitespace(raw);
+  if (!normalized) {
+    return "";
+  }
+  if (!containsReasoningLeak(normalized)) {
+    return stripWrappingQuotes(normalized);
+  }
+  const candidates = raw.split(/\n{2,}/).map((chunk) => stripWrappingQuotes(normalizeWhitespace(chunk))).filter(Boolean).filter((chunk) => !containsReasoningLeak(chunk)).filter((chunk) => !/^(role|task|guidelines|thinking|thinking process|attempt|critique|final decision|analysis)\b/i.test(chunk)).filter((chunk) => !/^[-*]\s/.test(chunk)).filter((chunk) => !/^\d+\.\s/.test(chunk));
+  return candidates.at(-1) ?? stripWrappingQuotes(normalized);
+}
+function containsReasoningLeak(text) {
+  return /(thinking process|analyze the request|drafting the optimized prompt|critique \d|attempt \d|final decision)/i.test(text);
+}
+function stripWrappingQuotes(text) {
+  return text.replace(/^["'`]+|["'`]+$/g, "").trim();
+}
+function isCodeFirstRequest(input) {
+  if (input.task === "code" || input.preset === "code") {
+    return true;
+  }
+  if ((input.targetHints ?? []).some((hint) => ["coding", "agentic", "refactor", "debugging", "tool_use", "architecture"].includes(hint))) {
+    return true;
+  }
+  return /\b(code|coding|repo|repository|refactor|patch|debug|bug|ci|test|typescript|javascript|agent|tool)\b/i.test(
+    input.prompt
+  );
+}
+function buildGeneralHeuristicPrompt(input, constraints) {
+  return [
+    `Request: ${summarizePrompt(input.prompt, 320)}`,
+    input.task ? `Task type: ${input.task}` : "",
+    input.tone ? `Tone: ${input.tone}` : "",
+    input.outputFormat ? `Output format: ${input.outputFormat}` : "",
+    input.maxLength ? `Maximum length: ${input.maxLength}` : "",
+    constraints.length ? `Critical constraints: ${constraints.join("; ")}` : ""
+  ].filter(Boolean);
+}
+function buildCodeFirstHeuristicPrompt(input, constraints) {
+  const deliverables = inferCodeDeliverables(input.prompt);
+  return [
+    `Goal: ${summarizeCodeGoal(input.prompt)}`,
+    input.tone ? `Tone: ${input.tone}` : "",
+    deliverables.length ? `Deliverables:
+- ${deliverables.join("\n- ")}` : "",
+    constraints.length ? `Constraints: ${constraints.join("; ")}` : "",
+    "Use a Karpathy loop: inspect, plan, act, test, reflect, repeat."
+  ].filter(Boolean);
+}
+function summarizePrompt(prompt, maxLength) {
+  const normalized = normalizeWhitespace(prompt);
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxLength - 1).trim()}\u2026`;
+}
+function summarizeCodeGoal(prompt) {
+  const normalized = summarizePrompt(prompt, 220);
+  const lowered = prompt.toLowerCase();
+  if (/auth|authentication|login|token/.test(lowered)) {
+    return "Inspect the codebase, understand the authentication flow, and produce a safe incremental refactor plan.";
+  }
+  if (/ci|debug|failing|failure|test/.test(lowered)) {
+    return "Inspect the codebase and failing signals, identify root causes, and produce a practical debugging plan.";
+  }
+  if (/refactor/.test(lowered)) {
+    return "Inspect the codebase and produce a phased refactor plan with minimal-risk execution steps.";
+  }
+  return normalized;
+}
+function inferCodeDeliverables(prompt) {
+  const lowered = prompt.toLowerCase();
+  const deliverables = [];
+  if (/inspect|codebase|repo|repository/.test(lowered)) {
+    deliverables.push("Summarize the relevant modules, ownership boundaries, and current behavior.");
+  }
+  if (/shared abstraction|shared abstractions|duplicate|duplicated/.test(lowered)) {
+    deliverables.push("Identify duplicated logic and the best shared abstractions to extract.");
+  }
+  if (/incremental|phase|phased|rollout|step/.test(lowered)) {
+    deliverables.push("Propose an incremental plan with small, reversible steps.");
+  }
+  if (/risk|migration|compatibility|backward/.test(lowered)) {
+    deliverables.push("Call out migration risks, compatibility concerns, and rollback points.");
+  }
+  if (/test|tests/.test(lowered)) {
+    deliverables.push("List the tests or validation needed before and after each phase.");
+  }
+  if (/avoid hand-wavy|practical|concrete/.test(lowered)) {
+    deliverables.push("Keep the recommendations concrete, implementation-oriented, and free of vague architecture advice.");
+  }
+  if (deliverables.length === 0) {
+    deliverables.push("Produce a compact, execution-ready plan for the coding task.");
+  }
+  return deliverables.slice(0, 6);
+}
 
 // src/index.ts
 function createOptimizer(config = {}) {
   return new PromptOptimizer(config);
 }
 
+// src/cliWelcome.ts
+import { basename } from "path";
+var MIN_WIDE_COLUMNS = 76;
+var PANEL_RULE = "__PANEL_RULE__";
+function renderWelcomeScreen(options) {
+  const columns = Math.max(60, options.columns ?? 100);
+  const color = options.color ?? false;
+  const user = options.user?.trim() || "pilot";
+  return columns >= MIN_WIDE_COLUMNS ? renderWideWelcome({ ...options, columns, color, user }) : renderCompactWelcome({ ...options, columns, color, user });
+}
+function renderWideWelcome(options) {
+  const width = clamp(options.columns - 4, 76, 118);
+  const innerWidth = width - 2;
+  const leftWidth = 30;
+  const rightWidth = innerWidth - leftWidth - 5;
+  const title = ` PromptPilot v${options.version} `;
+  const leftLines = [
+    style(`Welcome back ${capitalize(options.user)}!`, "bold", options.color),
+    "",
+    ...paintSprite(options.color),
+    "",
+    style(`${options.user} \u2022 ${basename(options.cwd)}`, "dim", options.color),
+    style(options.cwd, "dim", options.color)
+  ];
+  const rightLines = [
+    style("Tips for getting started", "accent", options.color),
+    "Run " + style('promptpilot optimize "fix this CI failure" --task code --plain', "bold", options.color),
+    "Pipe directly into Claude with " + style("| claude", "bold", options.color),
+    PANEL_RULE,
+    style("Local setup", "accent", options.color),
+    "Use " + style("--model promptpilot-compressor", "bold", options.color) + " for text-only local compression",
+    "",
+    style("Commands", "accent", options.color),
+    "optimize  optimize, compress, and route prompts",
+    "--help    show the full CLI reference"
+  ];
+  const rowCount = Math.max(leftLines.length, rightLines.length);
+  const topRule = renderTopRule(title, innerWidth, options.color);
+  const bottomRule = `${style("\u2570", "accent", options.color)}${style("\u2500".repeat(innerWidth), "accent", options.color)}${style("\u256F", "accent", options.color)}`;
+  const body = new Array(rowCount).fill(null).map((_, index) => {
+    const left = padVisible(leftLines[index] ?? "", leftWidth);
+    const rightLine = rightLines[index] ?? "";
+    const right = rightLine === PANEL_RULE ? style("\u2500".repeat(rightWidth), "dim", options.color) : padVisible(rightLine, rightWidth);
+    return `${style("\u2502", "accent", options.color)} ${left} ${style("\u2502", "accent", options.color)} ${right} ${style("\u2502", "accent", options.color)}`;
+  });
+  const footer = [
+    "",
+    style("Ready when you are.", "dim", options.color),
+    `Run ${style("promptpilot --help", "bold", options.color)} for the full option list.`
+  ];
+  return [topRule, ...body, bottomRule, ...footer].join("\n");
+}
+function renderCompactWelcome(options) {
+  const width = clamp(options.columns - 2, 58, 82);
+  const innerWidth = width - 2;
+  const title = ` PromptPilot v${options.version} `;
+  const lines = [
+    centerVisible(style(`Welcome back ${capitalize(options.user)}!`, "bold", options.color), innerWidth - 2),
+    "",
+    ...paintSprite(options.color).map((line) => centerVisible(line, innerWidth - 2)),
+    "",
+    style(options.cwd, "dim", options.color),
+    "",
+    style("Tips for getting started", "accent", options.color),
+    'promptpilot optimize "fix this CI failure" --task code --plain',
+    'promptpilot optimize "..." --model promptpilot-compressor',
+    "",
+    style("Help", "accent", options.color),
+    "promptpilot --help"
+  ];
+  return [
+    renderTopRule(title, innerWidth, options.color),
+    ...lines.map((line) => `${style("\u2502", "accent", options.color)} ${padVisible(line, innerWidth - 2)} ${style("\u2502", "accent", options.color)}`),
+    `${style("\u2570", "accent", options.color)}${style("\u2500".repeat(innerWidth), "accent", options.color)}${style("\u256F", "accent", options.color)}`
+  ].join("\n");
+}
+function paintSprite(color) {
+  const ink = color ? "\x1B[38;5;215m" : "";
+  const reset = color ? "\x1B[0m" : "";
+  return [
+    `${ink}      .-''''-.${reset}`,
+    `${ink}    .'  .--.  '.${reset}`,
+    `${ink}   /   / oo \\   \\${reset}`,
+    `${ink}  |    \\_==_/    |${reset}`,
+    `${ink}  |   .-.__.-.   |${reset}`,
+    `${ink}   \\  \\_/  \\_/  /${reset}`,
+    `${ink}    '._/|__|\\_.'${reset}`,
+    `${ink}      /_/  \\_\\${reset}`
+  ];
+}
+function style(text, tone, color) {
+  if (!color) {
+    return text;
+  }
+  switch (tone) {
+    case "accent":
+      return `\x1B[38;5;215m${text}\x1B[0m`;
+    case "bold":
+      return `\x1B[1m${text}\x1B[0m`;
+    case "dim":
+      return `\x1B[38;5;245m${text}\x1B[0m`;
+  }
+}
+function renderTopRule(title, innerWidth, color) {
+  const titleWidth = visibleWidth(title);
+  const leftRuleWidth = Math.min(3, Math.max(0, innerWidth - titleWidth));
+  const rightRuleWidth = Math.max(0, innerWidth - titleWidth - leftRuleWidth);
+  return `${style("\u256D", "accent", color)}${style("\u2500".repeat(leftRuleWidth), "accent", color)}${style(title, "accent", color)}${style("\u2500".repeat(rightRuleWidth), "accent", color)}${style("\u256E", "accent", color)}`;
+}
+function padVisible(text, targetWidth) {
+  const truncated = truncateVisible(text, targetWidth);
+  const padding = Math.max(0, targetWidth - visibleWidth(truncated));
+  return `${truncated}${" ".repeat(padding)}`;
+}
+function centerVisible(text, targetWidth) {
+  const truncated = truncateVisible(text, targetWidth);
+  const extra = Math.max(0, targetWidth - visibleWidth(truncated));
+  const leftPadding = Math.floor(extra / 2);
+  const rightPadding = extra - leftPadding;
+  return `${" ".repeat(leftPadding)}${truncated}${" ".repeat(rightPadding)}`;
+}
+function truncateVisible(text, targetWidth) {
+  if (visibleWidth(text) <= targetWidth) {
+    return text;
+  }
+  let visible = 0;
+  let result = "";
+  let inEscape = false;
+  for (const char of text) {
+    result += char;
+    if (char === "\x1B") {
+      inEscape = true;
+      continue;
+    }
+    if (inEscape) {
+      if (char === "m") {
+        inEscape = false;
+      }
+      continue;
+    }
+    visible += 1;
+    if (visible >= Math.max(0, targetWidth - 1)) {
+      break;
+    }
+  }
+  return `${result}\u2026`;
+}
+function visibleWidth(text) {
+  return text.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+function capitalize(value) {
+  if (value.length === 0) {
+    return value;
+  }
+  return value[0].toUpperCase() + value.slice(1);
+}
+
 // src/cli.ts
-async function runCli(argv, io = { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin }, dependencies = { createOptimizer, readStdin }) {
+async function runCli(argv, io = { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin }, dependencies = { createOptimizer, readStdin, getCliInfo }) {
   const [command, ...rest] = argv;
-  if (!command || command === "--help" || command === "-h") {
+  if (!command) {
+    const info = (dependencies.getCliInfo ?? getCliInfo)(io.stdout);
+    if (io.stdout.isTTY) {
+      io.stdout.write(`${renderWelcomeScreen(info)}
+`);
+      return 0;
+    }
+    io.stdout.write(`${getHelpText()}
+`);
+    return 0;
+  }
+  if (command === "--help" || command === "-h" || command === "help") {
     io.stdout.write(`${getHelpText()}
 `);
     return 0;
@@ -1905,6 +2257,36 @@ async function readStdin(stdin = process.stdin) {
     stdin.on("error", reject);
   });
 }
+function getCliInfo(stdout) {
+  return {
+    cwd: process.cwd(),
+    version: readPackageVersion(),
+    color: shouldUseColor(stdout),
+    columns: stdout.columns,
+    user: process.env.USER ?? process.env.USERNAME
+  };
+}
+function shouldUseColor(stdout) {
+  if (!stdout.isTTY) {
+    return false;
+  }
+  if (process.env.NO_COLOR) {
+    return false;
+  }
+  if (process.env.TERM === "dumb") {
+    return false;
+  }
+  return true;
+}
+function readPackageVersion() {
+  try {
+    const packageJson = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(packageJson);
+    return parsed.version ?? "dev";
+  } catch {
+    return "dev";
+  }
+}
 if (isMainModule()) {
   runCli(process.argv.slice(2)).then(
     (code) => {