@madebyseed/seed-cli-tools 3.0.0 → 4.0.0

package/src/tasks/watch-tui/classify.ts

@@ -0,0 +1,120 @@
+const ANSI_RE = /\x1B\[[0-9;?]*[ -/]*[@-~]/g;
+export const stripAnsi = (s: string): string => s.replace(ANSI_RE, "");
+const GULP_TIME = /^\[\d{2}:\d{2}:\d{2}\]\s*/;
+const CONT_PREFIX = /^›\s?/;
+
+export type EventKind =
+  | "build-start"
+  | "build-done"
+  | "build-error"
+  | "file-change"
+  | "upload"
+  | "error"
+  | "warn"
+  | "info"
+  | "verbose";
+
+export type Event =
+  | { kind: "build-start"; task: string }
+  | { kind: "build-done"; task: string; ms: number }
+  | { kind: "build-error"; task: string }
+  | {
+      kind: "file-change";
+      root: "src" | "dist";
+      dir: string;
+      file: string;
+      event: string;
+    }
+  | { kind: "upload"; message: string }
+  | { kind: "error"; message: string }
+  | { kind: "warn"; message: string }
+  | { kind: "info"; message: string }
+  | { kind: "verbose"; message: string };
+
+const ERROR_PATTERNS: RegExp[] = [
+  /^Error\b/,
+  /^Error in plugin\b/i,
+  /^'[^']+' errored after/,
+  /^Failed\b/i,
+  /^Cannot\b/i,
+  /^(TypeError|SyntaxError|ReferenceError|RangeError):/,
+  /^\s+at\s+\S+\s+\(.+:\d+:\d+\)/,
+  /^[✖✗✘⨯×]/,
+];
+
+const WARN_PATTERNS: RegExp[] = [
+  /^Warning\b/i,
+  /^\[?warn(ing)?\]?[:\s]/i,
+  /^⚠/,
+  /^\(node:\d+\).*(Warning|deprecat)/i,
+  /\bdeprecat(ed|ion)\b/i,
+];
+
+export function classify(raw: string): Event | null {
+  const stripped = stripAnsi(raw).trim();
+  if (!stripped) return null;
+
+  const withoutTime = stripped.replace(GULP_TIME, "").replace(CONT_PREFIX, "");
+
+  const startMatch = withoutTime.match(/^Starting '([^']+)'/);
+  if (startMatch) return { kind: "build-start", task: startMatch[1] };
+
+  const doneMatch = withoutTime.match(
+    /^Finished '([^']+)' after ([\d.]+)\s*(ms|s|μs)/,
+  );
+  if (doneMatch) {
+    const n = parseFloat(doneMatch[2]);
+    const unit = doneMatch[3];
+    const ms = unit === "s" ? n * 1000 : unit === "μs" ? n / 1000 : n;
+    return { kind: "build-done", task: doneMatch[1], ms };
+  }
+
+  const erroredMatch = withoutTime.match(/^'([^']+)' errored after/);
+  if (erroredMatch) return { kind: "build-error", task: erroredMatch[1] };
+
+  const fileChange = withoutTime.match(
+    /^(change in|updated dist)\s+(.+?)\s+-\s+(\w+)\s+(.+)$/,
+  );
+  if (fileChange) {
+    return {
+      kind: "file-change",
+      root: fileChange[1] === "updated dist" ? "dist" : "src",
+      dir: fileChange[2],
+      event: fileChange[3],
+      file: fileChange[4],
+    };
+  }
+
+  if (WARN_PATTERNS.some((re) => re.test(withoutTime))) {
+    return { kind: "warn", message: withoutTime };
+  }
+
+  if (ERROR_PATTERNS.some((re) => re.test(withoutTime))) {
+    return { kind: "error", message: withoutTime };
+  }
+
+  if (/(Synced|Uploaded|Pushing|Uploading)/i.test(withoutTime)) {
+    return { kind: "upload", message: withoutTime };
+  }
+
+  if (/^[-═─=]+$/.test(withoutTime)) {
+    return { kind: "verbose", message: withoutTime };
+  }
+
+  return { kind: "info", message: withoutTime };
+}
+
+/**
+ * Pick the most useful one-line summary from a multi-line error block.
+ */
+export function pickErrorSummary(lines: string[]): string {
+  const failed = lines.find((l) => /^Failed\s/i.test(l));
+  if (failed) return failed;
+  const errPrefix = lines.find((l) => /^Error:/.test(l));
+  if (errPrefix) return errPrefix.replace(/^Error:\s*/, "");
+  const pluginHeader = lines.find((l) => /^Error in plugin/i.test(l));
+  const meaningful = lines.find(
+    (l) => !/^(Message|Stack|Details|fileName|lineNumber):\s*$/i.test(l),
+  );
+  return pluginHeader || meaningful || lines[0];
+}

package/src/tasks/watch-tui/index.ts

@@ -0,0 +1,342 @@
+import React from "react";
+import { render, Instance } from "ink";
+import { classify, pickErrorSummary, stripAnsi } from "./classify";
+import { ShopifyParser, ShopifySignal } from "./shopify-parse";
+import { TuiStore } from "./state";
+import { loadThemeInfo } from "./theme-info";
+import { App } from "./App";
+
+const ERROR_FLUSH_MS = 150;
+/**
+ * Per-save builds bypass gulp's task system, so we can't pair their start
+ * and end events. Instead, on a src file-change we just flip to "building"
+ * for a short blink, then back to "watching". Pure visual feedback.
+ */
+const SAVE_BLINK_MS = 600;
+/**
+ * Tail size for the raw-output ring buffer dumped on non-zero exit. Big enough
+ * to capture a typical gulp error block (header + stack + plugin context),
+ * small enough not to flood the terminal.
+ */
+const TAIL_BUFFER_SIZE = 60;
+
+/**
+ * Tasks we don't want to clutter `lastBuild` with — meta steps and watchers.
+ * Their state transitions still go through normally; we just keep them out
+ * of the "last build: X" reading on the dashboard.
+ */
+const IGNORED_LAST_BUILD = /^(watch:|shopify:serve|output:errors$|clean$)/;
+
+/**
+ * "Errors" that are really just downstream wrappers re-reporting an upstream
+ * failure. They're meaningless on their own (and crowd out the actual cause),
+ * so we keep them out of the structured `lastError`. They still flow into the
+ * logs and the tail-buffer dump.
+ *
+ * - `Error: exited with error code: N` — emitted by `end-of-stream` when a
+ *   child process gulp is watching dies with a non-zero exit code. The real
+ *   error happened earlier in stderr.
+ */
+const WRAPPER_ERROR_PATTERNS: RegExp[] = [
+  /^Error: (Command )?(failed|exited)( with (error )?code)?:?\s*\d+/i,
+];
+const ALT_SCREEN_ENTER = "\x1b[?1049h";
+const ALT_SCREEN_LEAVE = "\x1b[?1049l";
+const CLEAR_SCREEN = "\x1b[2J\x1b[H";
+const CURSOR_HIDE = "\x1b[?25l";
+const CURSOR_SHOW = "\x1b[?25h";
+
+export interface TuiOptions {
+  verbose?: boolean;
+  sourceLabel?: string;
+  storeKey?: string;
+  cwd?: string;
+  onQuit?: () => void;
+}
+
+export class WatchTui {
+  private store: TuiStore;
+  private opts: TuiOptions;
+  private instance?: Instance;
+  private stopped = false;
+  private useAltScreen: boolean;
+
+  private errorBuffer: string[] = [];
+  private errorFlushTimer?: NodeJS.Timeout;
+  private shopify = new ShopifyParser();
+  private saveBlinkTimer?: NodeJS.Timeout;
+  // Raw output ring buffer — what we'd dump as a "tail" on unexpected exit.
+  // Both streams kept so the dump can flag which side a line came from.
+  private tailBuffer: { line: string; fromStderr: boolean }[] = [];
+
+  constructor(opts: TuiOptions = {}) {
+    this.opts = opts;
+    this.useAltScreen = Boolean(process.stdout.isTTY);
+    const themeInfo = loadThemeInfo(
+      opts.cwd || process.cwd(),
+      opts.storeKey || "main",
+    );
+    this.store = new TuiStore({
+      sourceLabel: opts.sourceLabel,
+      themeInfo,
+    });
+  }
+
+  start(): void {
+    if (this.useAltScreen) {
+      process.stdout.write(ALT_SCREEN_ENTER);
+      process.stdout.write(CLEAR_SCREEN);
+      process.stdout.write(CURSOR_HIDE);
+    }
+
+    this.instance = render(
+      React.createElement(App, {
+        store: this.store,
+        onQuit: () => this.requestQuit(),
+      }),
+      {
+        stdout: process.stdout,
+        stdin: process.stdin,
+        exitOnCtrlC: false,
+        patchConsole: false,
+      },
+    );
+  }
+
+  stop(exitCode?: number | null): void {
+    if (this.stopped) return;
+
+    if (this.saveBlinkTimer) clearTimeout(this.saveBlinkTimer);
+    this.flushErrorBuffer();
+    this.stopped = true;
+
+    if (this.instance) {
+      this.instance.unmount();
+      this.instance = undefined;
+    }
+
+    if (this.useAltScreen) {
+      process.stdout.write(CURSOR_SHOW);
+      process.stdout.write(ALT_SCREEN_LEAVE);
+    }
+
+    this.printFinalSummary(exitCode);
+  }
+
+  ingest(line: string, fromStderr: boolean): void {
+    // Always buffer the raw line — the safety net for "watch died and there's
+    // nothing in lastError to explain why." Trim leading/trailing whitespace
+    // but preserve the rest verbatim so stack traces stay readable on dump.
+    this.tailBuffer.push({ line, fromStderr });
+    if (this.tailBuffer.length > TAIL_BUFFER_SIZE) this.tailBuffer.shift();
+
+    this.applyShopifySignals(this.shopify.ingest(line));
+
+    const event = classify(line);
+    if (!event) return;
+
+    const inErrorWindow = this.errorFlushTimer !== undefined;
+
+    if (event.kind === "error") {
+      this.pushErrorLine(event.message);
+      this.store.pushLog("error", event.message);
+      return;
+    }
+
+    if (event.kind === "build-error") {
+      this.store.pushLog("build-error", `${event.task} failed`);
+      this.openErrorWindow();
+      this.store.setState("error");
+      return;
+    }
+
+    if (
+      inErrorWindow &&
+      fromStderr &&
+      (event.kind === "info" || event.kind === "verbose")
+    ) {
+      this.pushErrorLine(event.message);
+      this.store.pushLog("error", event.message);
+      return;
+    }
+
+    if (inErrorWindow) this.flushErrorBuffer();
+
+    switch (event.kind) {
+      case "build-start":
+        this.store.pushLog("build-start", `building ${event.task}`);
+        // The long-running watchers (watch:src, watch:css, ...) emit
+        // Starting but never Finished — letting them set "building" pins
+        // the state forever if their Starting lands after the last Finished
+        // during the parallel-watcher race at startup.
+        if (!IGNORED_LAST_BUILD.test(event.task)) {
+          this.store.setState("building");
+        }
+        break;
+      case "build-done":
+        this.store.pushLog(
+          "build-done",
+          `built ${event.task} (${fmtMs(event.ms)})`,
+        );
+        if (!IGNORED_LAST_BUILD.test(event.task)) {
+          this.store.setState("watching");
+          this.store.setLastBuild({
+            task: event.task,
+            ms: event.ms,
+            at: Date.now(),
+          });
+        }
+        break;
+      case "file-change":
+        this.store.pushLog(
+          "file-change",
+          `${event.root}/${event.dir}/${event.file} (${event.event})`,
+        );
+        if (this.store.state === "starting") this.store.setState("watching");
+        // src save → brief "building…" blink so the dev sees feedback.
+        if (event.root === "src") this.blinkBuilding();
+        break;
+      case "upload":
+        this.store.pushLog("upload", event.message);
+        if (this.store.state === "starting") this.store.setState("watching");
+        break;
+      case "warn":
+        this.store.pushLog("warn", event.message);
+        break;
+      case "verbose":
+        if (this.opts.verbose) this.store.pushLog("verbose", event.message);
+        break;
+      case "info":
+      default:
+        this.store.pushLog("info", event.message);
+        break;
+    }
+  }
+
+  private blinkBuilding(): void {
+    this.store.setState("building");
+    if (this.saveBlinkTimer) clearTimeout(this.saveBlinkTimer);
+    this.saveBlinkTimer = setTimeout(() => {
+      this.saveBlinkTimer = undefined;
+      // Don't override an error state that came in during the blink.
+      if (this.store.state === "building") this.store.setState("watching");
+    }, SAVE_BLINK_MS);
+  }
+
+  private applyShopifySignals(signals: ShopifySignal[]): void {
+    for (const s of signals) {
+      if (s.kind === "auth-required") {
+        this.store.updateShopify({
+          authUrl: s.url,
+          authUserCode: s.userCode,
+        });
+        continue;
+      }
+
+      if (s.kind === "local-url") this.store.updateShopify({ localUrl: s.url });
+      else if (s.kind === "preview-url")
+        this.store.updateShopify({ previewUrl: s.url });
+      else if (s.kind === "editor-url")
+        this.store.updateShopify({ editorUrl: s.url });
+
+      // Any URL means auth has completed and the dev server is up — clear
+      // the pending auth banner.
+      if (this.store.shopify.authUrl) {
+        this.store.updateShopify({ authUrl: undefined, authUserCode: undefined });
+      }
+
+      if (this.store.state === "starting") this.store.setState("watching");
+    }
+  }
+
+  private requestQuit(): void {
+    if (this.opts.onQuit) {
+      this.opts.onQuit();
+    } else {
+      this.stop(0);
+      process.kill(process.pid, "SIGINT");
+    }
+  }
+
+  private pushErrorLine(message: string): void {
+    if (!message) return;
+    // Wrapper errors (downstream "child exited with code N" style) tell the
+    // user nothing on their own — keep them out of the structured error
+    // block. The actual cause sits in the tail buffer either way.
+    if (WRAPPER_ERROR_PATTERNS.some((re) => re.test(message))) return;
+    this.errorBuffer.push(message);
+    this.store.setState("error");
+    this.openErrorWindow();
+  }
+
+  private openErrorWindow(): void {
+    if (this.errorFlushTimer) clearTimeout(this.errorFlushTimer);
+    this.errorFlushTimer = setTimeout(
+      () => this.flushErrorBuffer(),
+      ERROR_FLUSH_MS,
+    );
+  }
+
+  private flushErrorBuffer(): void {
+    if (this.errorFlushTimer) {
+      clearTimeout(this.errorFlushTimer);
+      this.errorFlushTimer = undefined;
+    }
+    if (this.errorBuffer.length === 0) return;
+    const lines = dedupeConsecutive(this.errorBuffer);
+    this.errorBuffer = [];
+
+    const summary = pickErrorSummary(lines);
+    this.store.setLastError({ lines, summary, at: Date.now() });
+  }
+
+  private printFinalSummary(exitCode?: number | null): void {
+    const out = process.stdout;
+    const err = this.store.lastError;
+    const failed = typeof exitCode === "number" && exitCode !== 0;
+
+    if (err) {
+      // We captured a structured error block — show it.
+      out.write(`\n\x1b[31m⚠ Last error\x1b[0m\n`);
+      for (const line of err.lines) {
+        out.write(`  \x1b[31m${stripAnsi(line)}\x1b[0m\n`);
+      }
+    }
+
+    // On non-zero exit, also dump the raw output tail. Even when we have a
+    // structured `lastError`, the captured block is often just the tip of the
+    // failure — the actual cause might be earlier stderr lines that didn't
+    // match an ERROR_PATTERN. Always showing the tail means the user always
+    // has the full context.
+    if (failed && this.tailBuffer.length > 0) {
+      out.write(
+        `\n\x1b[31m⚠ Output tail (last ${this.tailBuffer.length} lines):\x1b[0m\n`,
+      );
+      for (const entry of this.tailBuffer) {
+        const tag = entry.fromStderr ? "\x1b[31merr\x1b[0m" : "\x1b[90mout\x1b[0m";
+        out.write(`  ${tag} ${stripAnsi(entry.line)}\n`);
+      }
+    }
+
+    if (failed) {
+      out.write(`\n\x1b[31m✗ watch exited (code ${exitCode})\x1b[0m\n`);
+    } else {
+      out.write(`\n\x1b[90m✓ watch exited\x1b[0m\n`);
+    }
+  }
+}
+
+function dedupeConsecutive(lines: string[]): string[] {
+  const result: string[] = [];
+  for (const l of lines) {
+    if (result.length === 0 || result[result.length - 1] !== l) {
+      result.push(l);
+    }
+  }
+  return result;
+}
+
+function fmtMs(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}

package/src/tasks/watch-tui/shopify-parse.ts

@@ -0,0 +1,103 @@
+import { stripAnsi } from "./classify";
+
+export type ShopifySignalKind =
+  | "local-url"
+  | "preview-url"
+  | "editor-url"
+  | "auth-required";
+
+export interface ShopifySignal {
+  kind: ShopifySignalKind;
+  url: string;
+  /** Short user-facing code shopify shows to verify in the browser. */
+  userCode?: string;
+}
+
+const SHOPIFY_ELAPSED = /^\s*\d{2}:\d{2}:\d{2}\s+/;
+const BRACKET_TIME = /^\[\d{2}:\d{2}:\d{2}\]\s*/;
+const BOX_CHARS = /^[│╭╰─╮╯\s]+/;
+const BOX_END = /[│╮╯─\s]+$/;
+
+// Each shopify URL is self-identifying, so we pattern-match them directly
+// instead of tracking the "Next steps" menu and [N] footnote slots.
+const URL_RE = /https?:\/\/\S+/g;
+const QUERY_FRAGMENT = /^[A-Za-z0-9_=&%.\-]+$/;
+
+/**
+ * Stateful parser for the `shopify theme dev` console output.
+ *
+ * Extracts three URLs we care about (local / preview / editor) wherever they
+ * appear. Shopify wraps long URLs mid-query onto the next line, e.g.
+ *
+ *   [2] https://store.myshopify.com/admin/themes/123/editor?
+ *   hr=9292
+ *
+ * So if a URL ends in `?` or `&` we hold it and try to stitch the following
+ * line back on.
+ */
+export class ShopifyParser {
+  private pending?: string;
+
+  ingest(raw: string): ShopifySignal[] {
+    const line = normalize(raw);
+    if (!line) return [];
+
+    if (this.pending) {
+      if (QUERY_FRAGMENT.test(line)) {
+        const stitched = this.pending + line;
+        this.pending = undefined;
+        return this.extract(stitched);
+      }
+      // Not a continuation — abandon the incomplete url and parse this line.
+      this.pending = undefined;
+    }
+
+    // Device-code auth prompt:
+    //   👉 Open this link to start the auth process: https://accounts.shopify.com/activate-with-code?device_code%5Buser_code%5D=NCDB-HQVF
+    // We surface the URL and the user_code on the dashboard so the dev knows
+    // to click through. Don't return early — let URL extraction below
+    // capture the same URL into the auth-required signal.
+    const authMatch = line.match(
+      /Open this link to start the auth process:\s*(https?:\/\/\S+)/i,
+    );
+    if (authMatch) {
+      const url = authMatch[1];
+      const codeMatch = url.match(/user_code(?:%5D|\])=([A-Z0-9-]+)/i);
+      return [{ kind: "auth-required", url, userCode: codeMatch?.[1] }];
+    }
+
+    return this.extract(line);
+  }
+
+  private extract(line: string): ShopifySignal[] {
+    const signals: ShopifySignal[] = [];
+    URL_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = URL_RE.exec(line)) !== null) {
+      const url = m[0];
+      if (url.endsWith("?") || url.endsWith("&")) {
+        this.pending = url;
+        continue;
+      }
+      const kind = classifyUrl(url);
+      if (kind) signals.push({ kind, url });
+    }
+    return signals;
+  }
+}
+
+function classifyUrl(url: string): ShopifySignalKind | null {
+  // Local dev server — reject subpath variants (e.g. the gift_cards preview).
+  if (/^http:\/\/127\.0\.0\.1:\d+\/?$/.test(url)) return "local-url";
+  if (/\/admin\/themes\/\d+\/editor/.test(url)) return "editor-url";
+  if (/[?&]preview_theme_id=\d+/.test(url)) return "preview-url";
+  return null;
+}
+
+function normalize(raw: string): string {
+  let s = stripAnsi(raw);
+  s = s.replace(BRACKET_TIME, "");
+  s = s.replace(SHOPIFY_ELAPSED, "");
+  s = s.replace(BOX_CHARS, "").replace(BOX_END, "");
+  return s.trim();
+}

package/src/tasks/watch-tui/state.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from "events";
+import type { EventKind } from "./classify";
+
+export type WatchState = "starting" | "watching" | "building" | "error";
+
+export interface LastBuild {
+  task: string;
+  ms: number;
+  at: number;
+}
+
+export interface LastError {
+  lines: string[];
+  summary: string;
+  at: number;
+}
+
+export interface LogEntry {
+  id: number;
+  ts: number;
+  kind: EventKind;
+  text: string;
+}
+
+export interface ThemeInfo {
+  contextName?: string;
+  contextStatus?: string;
+  branch?: string;
+  baseBranch?: string;
+  storeDomain?: string;
+  previewThemeName?: string;
+  previewThemeId?: string;
+  previewUrl?: string;
+  customizerUrl?: string;
+  asanaTaskUrl?: string;
+  prUrl?: string;
+}
+
+export interface ShopifyStatus {
+  localUrl?: string;
+  previewUrl?: string;
+  editorUrl?: string;
+  /** Set when shopify cli prompts for device-code auth; clears once any
+   *  shopify URL arrives (auth completed and the dev server booted). */
+  authUrl?: string;
+  authUserCode?: string;
+}
+
+const MAX_LOGS = 5000;
+
+/**
+ * Flag-based state machine — same model the original draft used. Any
+ * meaningful event flips the state directly; no in-flight counter to get
+ * stuck. The Outcome line in App.tsx is just a translation of (state,
+ * lastBuild, lastError) into one line.
+ */
+export class TuiStore extends EventEmitter {
+  state: WatchState = "starting";
+  lastBuild?: LastBuild;
+  lastError?: LastError;
+  logs: LogEntry[] = [];
+  themeInfo?: ThemeInfo;
+  shopify: ShopifyStatus = {};
+  sourceLabel?: string;
+  startedAt = Date.now();
+  private seq = 0;
+
+  constructor(opts: { sourceLabel?: string; themeInfo?: ThemeInfo } = {}) {
+    super();
+    this.sourceLabel = opts.sourceLabel;
+    this.themeInfo = opts.themeInfo;
+  }
+
+  pushLog(kind: EventKind, text: string): LogEntry {
+    const entry: LogEntry = {
+      id: ++this.seq,
+      ts: Date.now(),
+      kind,
+      text,
+    };
+    this.logs.push(entry);
+    if (this.logs.length > MAX_LOGS) this.logs.shift();
+    this.emit("change");
+    return entry;
+  }
+
+  setState(next: WatchState): void {
+    if (this.state === next) return;
+    this.state = next;
+    this.emit("change");
+  }
+
+  setLastBuild(build: LastBuild): void {
+    this.lastBuild = build;
+    this.emit("change");
+  }
+
+  setLastError(err: LastError): void {
+    this.lastError = err;
+    this.state = "error";
+    this.emit("change");
+  }
+
+  clearLastError(): void {
+    this.lastError = undefined;
+    this.emit("change");
+  }
+
+  updateShopify(patch: Partial<ShopifyStatus>): void {
+    this.shopify = { ...this.shopify, ...patch };
+    this.emit("change");
+  }
+}