@checkstack/scripts 0.3.4 → 0.4.0

package/src/tui/components.tsx

@@ -0,0 +1,159 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { defaultTheme } from "./theme.ts";
+import type { TuiLevel, TuiStatus, TuiTheme } from "./theme.ts";
+
+/**
+ * Thin, reusable ink primitives built over the theme tokens. These have no
+ * dev-TUI-specific knowledge, so the CLI can adopt them later. Each accepts an
+ * optional `theme` so callers can override tokens without forking the kit.
+ */
+
+export interface StatusDotProps {
+  status: TuiStatus;
+  theme?: TuiTheme;
+}
+
+/** A single colored status dot. */
+export function StatusDot({
+  status,
+  theme = defaultTheme,
+}: StatusDotProps): React.ReactElement {
+  return <Text color={theme.status[status]}>●</Text>;
+}
+
+/** Braille spinner frames (smooth, monospace-safe, single column). */
+export const SPINNER_FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏",
+] as const;
+
+export interface SpinnerProps {
+  /** Monotonic tick; the rendered glyph is `frame % SPINNER_FRAMES.length`. */
+  frame: number;
+  /** Glyph color (defaults to the chrome accent). */
+  color?: string;
+  theme?: TuiTheme;
+}
+
+/**
+ * A controlled spinner: it renders the glyph for the given `frame` and holds no
+ * timer itself, so the caller owns the animation cadence (and tests stay
+ * deterministic). Pair it with a `setInterval` that bumps `frame`.
+ */
+export function Spinner({
+  frame,
+  color,
+  theme = defaultTheme,
+}: SpinnerProps): React.ReactElement {
+  const glyph = SPINNER_FRAMES[
+    ((frame % SPINNER_FRAMES.length) + SPINNER_FRAMES.length) %
+      SPINNER_FRAMES.length
+  ];
+  return <Text color={color ?? theme.chrome.accent}>{glyph}</Text>;
+}
+
+/** Line-wrapping behavior, mirroring ink's `Text` `wrap` prop. */
+export type TextWrap = React.ComponentProps<typeof Text>["wrap"];
+
+export interface LevelTextProps {
+  level: TuiLevel;
+  children: React.ReactNode;
+  theme?: TuiTheme;
+  /**
+   * Wrapping behavior. Pass `"truncate"` to keep a line to a single visual row
+   * (so a fixed-height pane cannot overflow when lines are long).
+   */
+  wrap?: TextWrap;
+}
+
+/** Text colored by log level (debug dimmed, warn yellow, error red). */
+export function LevelText({
+  level,
+  children,
+  theme = defaultTheme,
+  wrap,
+}: LevelTextProps): React.ReactElement {
+  return (
+    <Text color={theme.level[level]} dimColor={level === "debug"} wrap={wrap}>
+      {children}
+    </Text>
+  );
+}
+
+export interface PanelProps {
+  title?: string;
+  children: React.ReactNode;
+  theme?: TuiTheme;
+  /** Override the border color (defaults to the chrome border token). */
+  borderColor?: string;
+  /** Let the panel grow to fill available space in a flex column. */
+  flexGrow?: number;
+}
+
+/** A bordered box with an optional dim title row. */
+export function Panel({
+  title,
+  children,
+  theme = defaultTheme,
+  borderColor,
+  flexGrow,
+}: PanelProps): React.ReactElement {
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={borderColor ?? theme.chrome.border}
+      paddingX={1}
+      flexGrow={flexGrow}
+    >
+      {title === undefined ? null : (
+        <Box marginBottom={0}>
+          <Text color={theme.chrome.dim} bold>
+            {title}
+          </Text>
+        </Box>
+      )}
+      {children}
+    </Box>
+  );
+}
+
+export interface KeyHint {
+  /** The key or key combination, e.g. "q", "Tab", "PgUp". */
+  keys: string;
+  /** What the key does, e.g. "quit". */
+  label: string;
+}
+
+export interface KeyHintsProps {
+  hints: readonly KeyHint[];
+  theme?: TuiTheme;
+}
+
+/** A footer row rendering keybinding hints with accent-colored keys. */
+export function KeyHints({
+  hints,
+  theme = defaultTheme,
+}: KeyHintsProps): React.ReactElement {
+  return (
+    <Box>
+      {hints.map((hint, index) => (
+        <Box key={hint.keys} marginRight={index === hints.length - 1 ? 0 : 2}>
+          <Text color={theme.chrome.accent} bold>
+            {hint.keys}
+          </Text>
+          <Text color={theme.chrome.dim}> {hint.label}</Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/tui/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Reusable terminal-UI kit: theme tokens plus thin ink primitives. The kit is
+ * self-contained and has a one-way dependency contract (consumers depend on the
+ * kit, never the reverse), so the plugin CLI can adopt it without a refactor.
+ */
+export { defaultTheme } from "./theme.ts";
+export type {
+  TuiTheme,
+  TuiLevel,
+  TuiStatus,
+  LevelColors,
+  StatusColors,
+  ChromeColors,
+} from "./theme.ts";
+
+export {
+  StatusDot,
+  Spinner,
+  SPINNER_FRAMES,
+  LevelText,
+  Panel,
+  KeyHints,
+} from "./components.tsx";
+export type {
+  StatusDotProps,
+  SpinnerProps,
+  LevelTextProps,
+  PanelProps,
+  KeyHintsProps,
+  KeyHint,
+} from "./components.tsx";

package/src/tui/theme.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test";
+import { defaultTheme } from "./theme.ts";
+import type { TuiLevel, TuiStatus } from "./theme.ts";
+
+const ALL_LEVELS: TuiLevel[] = ["debug", "info", "warn", "error"];
+const ALL_STATUSES: TuiStatus[] = [
+  "starting",
+  "ready",
+  "errored",
+  "stopped",
+];
+
+describe("defaultTheme", () => {
+  it("defines a non-empty color for every level", () => {
+    for (const level of ALL_LEVELS) {
+      expect(defaultTheme.level[level]).toBeString();
+      expect(defaultTheme.level[level].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("defines a non-empty color for every status", () => {
+    for (const status of ALL_STATUSES) {
+      expect(defaultTheme.status[status]).toBeString();
+      expect(defaultTheme.status[status].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("defines all chrome tokens", () => {
+    expect(defaultTheme.chrome.border.length).toBeGreaterThan(0);
+    expect(defaultTheme.chrome.dim.length).toBeGreaterThan(0);
+    expect(defaultTheme.chrome.accent.length).toBeGreaterThan(0);
+    expect(defaultTheme.chrome.text.length).toBeGreaterThan(0);
+  });
+
+  it("uses the conventional alert colors (warn yellow, error red)", () => {
+    expect(defaultTheme.level.warn).toBe("yellow");
+    expect(defaultTheme.level.error).toBe("red");
+  });
+
+  it("maps the ready status to green and errored to red", () => {
+    expect(defaultTheme.status.ready).toBe("green");
+    expect(defaultTheme.status.errored).toBe("red");
+  });
+
+  it("does not contain duplicate keys between level and status maps", () => {
+    // Sanity: the two maps are independent records with their own key spaces.
+    expect(Object.keys(defaultTheme.level).sort()).toEqual(
+      [...ALL_LEVELS].sort(),
+    );
+    expect(Object.keys(defaultTheme.status).sort()).toEqual(
+      [...ALL_STATUSES].sort(),
+    );
+  });
+});

package/src/tui/theme.ts

@@ -0,0 +1,60 @@
+/**
+ * Theme tokens for the reusable terminal-UI kit. These are plain data (no ink
+ * imports) so they can be unit-tested and consumed by any ink component. The
+ * CLI can adopt the same kit later by importing {@link defaultTheme}.
+ *
+ * Color values are ink/chalk color names (resolved by ink at render time),
+ * keeping this module dependency-free and DOM-free.
+ */
+
+export type TuiLevel = "debug" | "info" | "warn" | "error";
+export type TuiStatus = "starting" | "ready" | "errored" | "stopped";
+
+/** Every level maps to exactly one color. */
+export type LevelColors = Readonly<Record<TuiLevel, string>>;
+/** Every status maps to exactly one color. */
+export type StatusColors = Readonly<Record<TuiStatus, string>>;
+
+/** Chrome colors: borders, dimmed labels, and the accent used for focus. */
+export interface ChromeColors {
+  /** Border color for panels and bordered boxes. */
+  readonly border: string;
+  /** Dimmed text for chrome / secondary labels. */
+  readonly dim: string;
+  /** Accent color for the focused tab / highlights. */
+  readonly accent: string;
+  /** Foreground for ordinary content text. */
+  readonly text: string;
+}
+
+export interface TuiTheme {
+  readonly level: LevelColors;
+  readonly status: StatusColors;
+  readonly chrome: ChromeColors;
+}
+
+/**
+ * The default theme: restrained color, dim chrome, bright content. Debug is
+ * dimmed gray, info default-ish, warn yellow, error red. Status dots follow the
+ * spec: starting yellow, ready green, errored red, stopped dim gray.
+ */
+export const defaultTheme: TuiTheme = {
+  level: {
+    debug: "gray",
+    info: "white",
+    warn: "yellow",
+    error: "red",
+  },
+  status: {
+    starting: "yellow",
+    ready: "green",
+    errored: "red",
+    stopped: "gray",
+  },
+  chrome: {
+    border: "gray",
+    dim: "gray",
+    accent: "cyan",
+    text: "white",
+  },
+};

package/src/utils/template.ts

@@ -17,6 +17,28 @@ export interface TemplateData {
   pluginId: string;
   pluginType: string;
   currentYear: number;
+  /**
+   * npm scope for the *generated* packages, WITHOUT the leading `@`
+   * (e.g. `acme`). Defaults to `checkstack` so the in-monorepo `create`
+   * command renders byte-for-byte identical output to before. An empty
+   * string means "publish the trio unscoped" (e.g. `widget-backend`),
+   * which the {@link scopedPackageName} helper handles.
+   */
+  packageScope: string;
+}
+
+/**
+ * Build a published package name from a scope + bare name. With a scope:
+ * `@acme/widget-backend`; without (empty scope): `widget-backend`.
+ */
+export function scopedPackageName({
+  packageScope,
+  name,
+}: {
+  packageScope: string;
+  name: string;
+}): string {
+  return packageScope ? `@${packageScope}/${name}` : name;
 }
 
 /**
@@ -45,6 +67,19 @@ export function registerHelpers() {
   Handlebars.registerHelper("year", () => {
     return new Date().getFullYear();
   });
+
+  // `{{scoped "widget-common"}}` -> `@<packageScope>/widget-common`, or
+  // just `widget-common` when packageScope is empty. The scope is read from
+  // the template data root so callers don't repeat it at every use site.
+  Handlebars.registerHelper(
+    "scoped",
+    function (this: { packageScope?: string }, name: string) {
+      return scopedPackageName({
+        packageScope: this.packageScope ?? "checkstack",
+        name,
+      });
+    },
+  );
 }
 
 /**
@@ -127,10 +162,16 @@ export function prepareTemplateData({
   baseName,
   pluginType,
   description,
+  packageScope = "checkstack",
 }: {
   baseName: string;
   pluginType: string;
   description: string;
+  /**
+   * npm scope (without `@`) for the generated packages. Defaults to
+   * `checkstack` (the monorepo scope); pass `""` for an unscoped trio.
+   */
+  packageScope?: string;
 }): TemplateData {
   const pluginName = `${baseName}-${pluginType}`;
   const pluginNamePascal = baseName
@@ -150,5 +191,6 @@ export function prepareTemplateData({
     pluginId: pluginName,
     pluginType,
     currentYear: new Date().getFullYear(),
+    packageScope,
   };
 }