agy-powerline 1.2.0 → 1.4.0

package/src/cli/configure.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const readline = require("readline");
 const { spawn } = require("child_process");
 const {
@@ -19,11 +21,10 @@ const {
   PRESETS,
   PRESET_ORDER,
   applyPreset,
-  resolveQuotaThresholds,
-  resolveContextThresholds,
 } = require("../lib/shared");
 const { resolveInstallDir } = require("../lib/paths");
 const { WIDGET_TAGS } = require("../lib/widget-style");
+const { editFields: getEditFields } = require("../lib/widget-options");
 const { loadEditableConfig } = require("./config-guard");
 const {
   parseColor,
@@ -48,7 +49,7 @@ const {
   glyphName,
 } = require("../lib/powerline");
 
-const REPO_URL = "https://github.com/wassim-azi/agy-powerline";
+const { REPO_URL } = require("./repo-url");
 
 const CSI = "\x1b[";
 const RESET = `${CSI}0m`;
@@ -294,7 +295,15 @@ const TAB_OF_SCREEN = {
   glyphs: "powerline",
 };
 
-const PRESET_ICONS = { default: "🎯", compact: "⚡", workspace: "📂", limits: "🔋", full: "🚀" };
+const PRESET_ICONS = {
+  default: "🎯",
+  compact: "⚡",
+  agent: "🧠",
+  git: "🔀",
+  tokens: "📊",
+  quotas: "🔋",
+  full: "🚀",
+};
 
 // Set by renderFrame so tests can draw a screen at a fixed size.
 let columnsOverride = null;
@@ -408,6 +417,7 @@ function previewParts(width) {
   // The toggle keys work on the widget list, so only that screen names them.
   const key = (letter) => (screen === "main" ? letter : "");
   const chips = [
+    ui.chip("gaps", preview.rowGap, key("v")),
     ui.chip("emojis", preview.emojis, key("e")),
     ui.chip("minimal", preview.minimalist, key("m")),
     ui.chip("pace", preview.pacing, key("r")),
@@ -415,10 +425,7 @@ function previewParts(width) {
     ui.chip("ascii", preview.ascii, key("i")),
   ];
   if (preview.layout === "pills") {
-    chips.unshift(
-      ui.chip("joins", preview.powerline.enabled, key("j")),
-      ui.chip("gaps", preview.rowGap, key("v"))
-    );
+    chips.unshift(ui.chip("joins", preview.powerline.enabled, key("j")));
   }
 
   return { title, bar: String(rendered).split("\n"), chips: chips.join("   ") };
@@ -749,151 +756,14 @@ function drawMain() {
   });
 }
 
-// Widgets that take each option, as the layouts read them.
-const QUOTA_WIDGETS = new Set([
-  "quota",
-  "fiveHourBar",
-  "fiveHourPct",
-  "weeklyBar",
-  "weeklyPct",
-  "thirdPartyFiveHour",
-  "thirdPartyWeekly",
-  "argonWeekly",
-]);
-const PACED_WIDGETS = new Set([
-  "fiveHourBar",
-  "weeklyBar",
-  "thirdPartyFiveHour",
-  "thirdPartyWeekly",
-  "argonWeekly",
-]);
-const CONTEXT_WIDGETS = new Set(["context", "contextPct", "contextTokens"]);
-const RESET_WIDGETS = new Set(["fiveHourReset", "weeklyReset", "argonReset"]);
-const COLOR_SLOTS = ["model", "context", "git", "weekly", "thirdParty", "fiveHour", "meta"];
 // Longest custom badge text; the badge is meant to be a word or two.
 const TEXT_MAX = 40;
 
-const onOff = (value) => (value ? "on" : "off");
-
-// The options of one widget: cycle fields step through values, number fields
-// step by 5 with the arrows, text fields take typing, and fixed ones only show
-// their value. undefined means "not set": the widget follows the global
-// setting or its default.
 function editFields(widget) {
-  const quota = QUOTA_WIDGETS.has(widget.id);
-  const context = CONTEXT_WIDGETS.has(widget.id);
-  const thresholds = quota
-    ? resolveQuotaThresholds({}, config)
-    : context
-      ? resolveContextThresholds({}, config)
-      : null;
-  const fields = [
-    {
-      key: "color",
-      label: "Color",
-      values: [undefined, ...COLOR_SLOTS],
-      show: (value) => (value === undefined ? "theme default" : colorName(value)),
-      help: "Draws this widget in another of the theme's colors. Caution and danger colors still take over when a quota or the context runs low.",
-    },
-    {
-      key: "raw",
-      label: "Label",
-      values: [undefined, false, true],
-      show: (value) =>
-        value === undefined
-          ? `default (${config.minimalist ? "hidden" : "shown"})`
-          : value
-            ? "hidden, value only"
-            : "shown",
-      help: "Shows or hides the icon and label before the value. Default follows minimalist mode (m).",
-    },
-  ];
-
-  if (widget.id === "model") {
-    fields.push({
-      key: "short",
-      label: "Short name",
-      values: [undefined, true],
-      show: (value) => onOff(value),
-      help: "3.8 Flash·High instead of Gemini 3.8 Flash (High).",
-    });
-  }
-  if (widget.id === "totalTokens") {
-    fields.push({
-      key: "split",
-      label: "Split",
-      values: [undefined, true],
-      show: (value) => onOff(value),
-      help: "Input and output tokens apart (123.1K↑ 355.0K↓) instead of one total.",
-    });
-  }
-  if (RESET_WIDGETS.has(widget.id)) {
-    fields.push({
-      key: "format",
-      label: "Format",
-      values: [undefined, "time", "both"],
-      show: (value) => value ?? "countdown",
-      help: "countdown (2hr 47m), time (6:33pm) or both (6:33pm (2hr 47m)).",
-    });
-  }
-  if (widget.id === "customText") {
-    fields.push({
-      key: "text",
-      label: "Text",
-      text: true,
-      show: (value) => value || "(empty: hidden)",
-      help: "The badge's text. Enter to type, Enter again to keep it, Esc to cancel.",
-    });
-  }
-  if (widget.id === "exec") {
-    fields.push({
-      key: "cmd",
-      label: "Command",
-      fixed: true,
-      show: (value) => value || "(none)",
-      help: `The command runs only in agy, from your install folder. Edit it in ${getConfigPath()}.`,
-    });
-  }
-  if (thresholds) {
-    const what = quota ? "left" : "used";
-    fields.push(
-      {
-        key: "warn",
-        label: "Caution at",
-        number: thresholds.warn,
-        show: (value) => (value === undefined ? `default (${thresholds.warn}%)` : `${value}%`),
-        help: `Turns to the caution color at this share ${what}.`,
-      },
-      {
-        key: "crit",
-        label: "Danger at",
-        number: thresholds.crit,
-        show: (value) => (value === undefined ? `default (${thresholds.crit}%)` : `${value}%`),
-        help: `Turns to the danger color at this share ${what}.`,
-      },
-      {
-        key: "blink",
-        label: "Blink",
-        values: [undefined, true, "warn", false],
-        show: (value) =>
-          value === undefined
-            ? `default (${thresholds.blink ? "on" : "off"})`
-            : { true: "at danger", warn: "at caution and danger", false: "off" }[String(value)],
-        help: "Makes the widget blink when it reaches the danger (or caution) level. ASCII mode never blinks.",
-      }
-    );
-  }
-  if (PACED_WIDGETS.has(widget.id)) {
-    fields.push({
-      key: "pace",
-      label: "Pace marker",
-      values: [undefined, false, true],
-      show: (value) =>
-        value === undefined ? `default (${onOff(config.pacing !== false)})` : onOff(value),
-      help: "Marks where usage would be if it were spread evenly over the window. Default follows r.",
-    });
-  }
-  return fields;
+  return getEditFields(widget, config, {
+    colorName: (value) => (value === undefined ? "theme default" : colorName(value)),
+    cmdHelp: `The command runs only in agy, from your install folder. Edit it in ${getConfigPath()}.`,
+  });
 }
 
 // A theme slot's color name, in that color.
@@ -1165,21 +1035,38 @@ const toHex = (rgb) => `#${rgb.map((part) => part.toString(16).padStart(2, "0"))
 
 // One color as a pill in that color with the theme's pill text, the way the
 // bar draws it, then its hex value.
-function colorLine(label, rgb, ink) {
-  return { raw: `${ui.pill(` ${label.padEnd(9)}`, rgb, ink)}  ${dim(toHex(rgb))}` };
-}
-
-const PALETTE_SLOTS = [
-  ["model", "Model"],
-  ["context", "Context"],
-  ["git", "Git"],
-  ["weekly", "7d quota"],
-  ["meta", "Details"],
-  ["fiveHour", "OK"],
-  ["caution", "Caution"],
-  ["warn", "Danger"],
+function colorCell(label, rgb, ink) {
+  return `${ui.pill(` ${label.padEnd(9)}`, rgb, ink)}  ${dim(toHex(rgb))}`;
+}
+
+// Widget colors on the left, states on the right; a blank line between rows
+// keeps the pills from touching.
+const PALETTE_ROWS = [
+  [
+    ["model", "Model"],
+    ["fiveHour", "OK"],
+  ],
+  [
+    ["context", "Context"],
+    ["caution", "Caution"],
+  ],
+  [
+    ["git", "Git"],
+    ["warn", "Danger"],
+  ],
+  [
+    ["weekly", "7d quota"],
+    ["meta", "Details"],
+  ],
 ];
 
+function paletteLines(colors) {
+  return PALETTE_ROWS.flatMap((row, index) => [
+    ...(index ? [""] : []),
+    { raw: row.map(([slot, label]) => colorCell(label, colors[slot], colors.text)).join("    ") },
+  ]);
+}
+
 function themeDetails(id) {
   if (id === "custom") {
     return {
@@ -1203,9 +1090,7 @@ function themeDetails(id) {
       ...(background ? [{ raw: `${dim("For")} ${ui.tag(background)}` }] : []),
       "",
       heading("Palette"),
-      ...PALETTE_SLOTS.map(([slot, label]) =>
-        colorLine(label, theme.colors[slot], theme.colors.text)
-      ),
+      ...paletteLines(theme.colors),
       "",
       heading("Sample"),
       ...themeSample(theme.colors),
@@ -1340,7 +1225,7 @@ const POWERLINE_HELP = {
   enabled:
     "On: adjacent widgets share one pill, with a separator between them. Off: every widget gets its own pill.",
   rowGap:
-    "Puts a blank line between Pills rows, so stacked pills don't touch. The bar takes more lines (three rows become five).",
+    "Puts a blank line between rows, in every layout, so stacked pills don't touch and text rows get more air. The bar takes more lines (three rows become five).",
   style: "Sets start caps, end caps and separators in one go. Enter cycles the styles.",
   separators: "Glyphs between widgets of a pill. With several, they cycle per join, left to right.",
   startCaps: "Glyphs that open each pill. With several, they cycle per pill, left to right.",
@@ -1369,7 +1254,7 @@ function powerlineDetails(row) {
 function drawPowerline() {
   const items = POWERLINE_ROWS.map((row) => ({ text: row.label, value: powerlineRowValue(row) }));
   const notes =
-    config.layout === "lines"
+    config.layout !== "pills"
       ? ["Powerline shapes apply to Pills. Switch layout with l."]
       : [
           "A style sets caps and separators together; edit a list to fine-tune it.",
@@ -1454,10 +1339,24 @@ function drawGlyphs() {
   });
 }
 
+// Three short paragraphs per layout, each under 90 columns so a wide panel
+// shows them unwrapped.
 const LAYOUT_HELP = {
-  pills: "Widgets sit in colored pills. The Powerline tab sets their caps, separators and joins.",
-  lines:
-    "Colored text on the terminal background, with dividers and dot meters. Powerline shapes don't apply.",
+  pills: [
+    "Widgets sit in colored pills, joined by powerline caps and separators.",
+    "Meters draw as small dots on the pill's color, with a larger dot as the pace marker.",
+    "The Powerline tab sets the caps, separators, joins and the space between rows.",
+  ],
+  lines: [
+    "Colored text on the terminal background, with thin │ dividers between widgets.",
+    "Meters draw as dots in the ok, caution or danger color, over a dim track.",
+    "Powerline shapes don't apply; the theme, widgets and space between rows do.",
+  ],
+  classic: [
+    "Colored text on the terminal background, with | dividers between widgets.",
+    "Meters draw as blocks in one color: █ filled, ░ empty and │ as the pace marker.",
+    "Powerline shapes don't apply; the theme, widgets and space between rows do.",
+  ],
 };
 
 function drawLayout() {
@@ -1471,10 +1370,9 @@ function drawLayout() {
   return screenFrame({
     title: "Layout",
     items,
-    notes: ["Both layouts use your widgets and theme; Powerline shapes apply to Pills."],
     details: hovered && {
       title: hovered.name,
-      lines: [`${hovered.description}.`, "", LAYOUT_HELP[hovered.id] ?? ""],
+      lines: LAYOUT_HELP[hovered.id].flatMap((line, i) => (i ? ["", line] : [line])),
     },
     keys: [
       [ui.glyph.upDown, "preview"],

package/src/cli/doctor.js

@@ -1,3 +1,5 @@
+"use strict";
+
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
@@ -23,6 +25,7 @@ const {
 const { runStatuslineCommand } = require("../lib/run");
 const { detectColorDepth } = require("../lib/colors");
 const { readLog, getLogPath } = require("../lib/log");
+const { USAGE_PERIODS, usageAvailable } = require("../lib/usage");
 const { version } = require("../../package.json");
 
 const DIM = "\x1b[2m";
@@ -144,6 +147,15 @@ async function doctorCommand(options = {}) {
     console.log("  The bar shows the defaults until you fix the file or delete it.");
   }
 
+  // Not a failure: the widgets just hide.
+  if (configState.config.widgets.some((widget) => USAGE_PERIODS[widget.id]) && !usageAvailable()) {
+    console.log();
+    console.log(
+      `${YELLOW} usage widgets need Node 22.13 or newer${RESET} (this is ${process.version}).`
+    );
+    console.log("  tokensToday and tokensWeek stay hidden until Node is updated.");
+  }
+
   const breaking = cmdBreakingChars(installDir);
   if (breaking.length) {
     failed += 1;

package/src/cli/export.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { readConfigFile, mergeConfig, setConfigDir } = require("../lib/shared");
+const { resolveInstallDir, writeFileAtomic, PRIVATE_FILE_MODE } = require("../lib/paths");
+const { printInvalidConfig } = require("./config-guard");
+const { version } = require("../../package.json");
+
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+
+// The config as the bar reads it, with the release that wrote it first, so an
+// import can tell a file from a newer release.
+function exportDocument(config) {
+  return { agyPowerline: { version }, ...mergeConfig(config) };
+}
+
+function execCommandCount(config) {
+  return (config.widgets || []).filter(
+    (widget) => widget.id === "exec" && String(widget.cmd || "").trim()
+  ).length;
+}
+
+async function exportCommand(file, options = {}) {
+  const installDir = resolveInstallDir();
+  if (!installDir) {
+    return;
+  }
+
+  setConfigDir(installDir);
+  const { config, error } = readConfigFile();
+  if (error) {
+    // Exporting the defaults would look like a backup of the user's bar.
+    printInvalidConfig(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const body = JSON.stringify(exportDocument(config), null, 2) + "\n";
+
+  if (file) {
+    const target = path.resolve(String(file));
+    let existing = null;
+    try {
+      existing = fs.statSync(target);
+    } catch {
+      // Nothing there yet.
+    }
+    if (existing?.isDirectory()) {
+      console.error(`${RED}error${RESET} ${target} is a folder. Name a file to write.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (existing && !options.force) {
+      console.error(`${RED}error${RESET} ${target} already exists. Pass --force to replace it.`);
+      process.exitCode = 1;
+      return;
+    }
+    // Owner-only, like the config itself: it can hold your commands.
+    writeFileAtomic(target, body, { mode: PRIVATE_FILE_MODE });
+    console.error(`${GREEN}✔${RESET} Config exported to ${DIM}${target}${RESET}`);
+  } else {
+    process.stdout.write(body);
+  }
+
+  // Notes go to stderr, so `export > file` keeps the JSON clean.
+  const commands = execCommandCount(config);
+  if (commands) {
+    console.error(
+      `${YELLOW}note${RESET} The export holds ${commands} exec widget command${commands === 1 ? "" : "s"}; check ${commands === 1 ? "it" : "them"} before sharing the file.`
+    );
+  }
+}
+
+module.exports = {
+  exportCommand,
+  exportDocument,
+};

package/src/cli/gradient.js

@@ -0,0 +1,121 @@
+"use strict";
+
+const {
+  saveConfig,
+  setConfigDir,
+  getConfigPath,
+  renderStatusline,
+  sampleData,
+  resolveColorDepth,
+} = require("../lib/shared");
+const { GRADIENTS, GRADIENT_ORDER, normalizeGradient, gradientStops } = require("../lib/themes");
+const { bg, gradientColors, setActiveDepth, getActiveDepth } = require("../lib/colors");
+const { resolveInstallDir } = require("../lib/paths");
+const { loadEditableConfig } = require("./config-guard");
+
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const RESET = "\x1b[0m";
+
+const STRIP_WIDTH = 24;
+
+// A row of colored cells showing the gradient; empty without color.
+function gradientStrip(value, config) {
+  const stops = gradientStops(value);
+  if (!stops) {
+    return "";
+  }
+  const previous = getActiveDepth();
+  setActiveDepth(resolveColorDepth({ configColor: config.color, env: process.env }));
+  try {
+    if (getActiveDepth() === "none") {
+      return "";
+    }
+    const cells = gradientColors(stops, STRIP_WIDTH).map((color) => `${bg(color)} `);
+    return `${cells.join("")}${RESET}`;
+  } finally {
+    setActiveDepth(previous);
+  }
+}
+
+function listGradients(config) {
+  const current = config.gradient || "off";
+
+  console.log();
+  console.log(`${BOLD} agy-powerline gradients${RESET}`);
+  console.log(`  current  ${CYAN}${current}${RESET} ${gradientStrip(config.gradient, config)}`);
+  console.log(`  config   ${DIM}${getConfigPath()}${RESET}`);
+  console.log();
+
+  const maxIdLen = Math.max(...GRADIENT_ORDER.map((id) => id.length), "off".length);
+
+  for (const id of [...GRADIENT_ORDER, "off"]) {
+    const isCurrent = id === current;
+    const marker = isCurrent ? `${GREEN}*${RESET}` : " ";
+    const idFormatted = isCurrent
+      ? `${BOLD}${CYAN}${id.padEnd(maxIdLen)}${RESET}`
+      : id.padEnd(maxIdLen);
+    const preview = id === "off" ? `${DIM}theme colors only${RESET}` : gradientStrip(id, config);
+    console.log(`  ${marker} ${idFormatted}  ${preview}`);
+  }
+
+  console.log();
+  console.log(` Run ${CYAN}npx agy-powerline gradient <name>${RESET} to color each row.`);
+  console.log(` Your own colors: ${CYAN}npx agy-powerline gradient "#ff5f6d-#ffc371"${RESET}`);
+  console.log();
+}
+
+async function gradientCommand(name, options = {}) {
+  const installDir = resolveInstallDir();
+  if (!installDir) {
+    return;
+  }
+
+  setConfigDir(installDir);
+  const config = loadEditableConfig();
+  if (!config) {
+    return;
+  }
+
+  if (!name || options.list) {
+    listGradients(config);
+    return;
+  }
+
+  const raw = String(name).trim();
+  const off = raw.toLowerCase() === "off";
+  const value = off ? null : normalizeGradient(raw);
+
+  if (!off && !value) {
+    console.error(`${RED}error${RESET} Unknown gradient "${raw}".`);
+    console.error(` Available gradients: ${GRADIENT_ORDER.join(", ")}, off`);
+    console.error(" Or 2 to 6 hex colors joined by dashes, e.g. #ff5f6d-#ffc371");
+    process.exitCode = 1;
+    return;
+  }
+
+  if (off) {
+    delete config.gradient;
+  } else {
+    config.gradient = value;
+  }
+  saveConfig(config);
+
+  const title = off ? "off" : GRADIENTS[value]?.name || value;
+
+  console.log();
+  console.log(`${GREEN}✔${RESET} Gradient set to ${BOLD}${title}${RESET}`);
+  console.log(`  config  ${DIM}${getConfigPath()}${RESET}`);
+  console.log();
+  console.log(" Preview:");
+  console.log(renderStatusline(sampleData(), config));
+  console.log();
+}
+
+module.exports = {
+  gradientCommand,
+  gradientStrip,
+};