gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

package/src/resources/extensions/shared/tests/interview-preview.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import { Markdown, visibleWidth } from "@gsd/pi-tui";
+import { getMarkdownTheme, initTheme } from "@gsd/pi-coding-agent";
+import type { QuestionOption, Question } from "../interview-ui.js";
+
+// Theme must be initialized before Markdown rendering
+before(() => { initTheme(); });
+
+// ─── QuestionOption.preview type contract ─────────────────────────────────────
+
+describe("QuestionOption preview field", () => {
+  it("accepts option without preview (backward compat)", () => {
+    const opt: QuestionOption = { label: "A", description: "Desc A" };
+    assert.equal(opt.preview, undefined);
+  });
+
+  it("accepts option with preview string", () => {
+    const opt: QuestionOption = {
+      label: "A",
+      description: "Desc A",
+      preview: "## Code\n```ts\nconst x = 1;\n```",
+    };
+    assert.equal(typeof opt.preview, "string");
+    assert.ok(opt.preview!.length > 0);
+  });
+
+  it("Question with mixed preview/no-preview options is valid", () => {
+    const q: Question = {
+      id: "test",
+      header: "Test",
+      question: "Pick one",
+      options: [
+        { label: "A", description: "Has preview", preview: "# Preview A" },
+        { label: "B", description: "No preview" },
+        { label: "C", description: "Has preview", preview: "# Preview C" },
+      ],
+    };
+    const withPreview = q.options.filter((o) => o.preview);
+    const withoutPreview = q.options.filter((o) => !o.preview);
+    assert.equal(withPreview.length, 2);
+    assert.equal(withoutPreview.length, 1);
+  });
+});
+
+// ─── Markdown preview rendering ───────────────────────────────────────────────
+
+describe("preview column rendering", () => {
+  it("Markdown component renders non-empty output for a markdown string", () => {
+    const mdTheme = getMarkdownTheme();
+    const md = new Markdown("## Hello\n\nSome **bold** text.", 1, 0, mdTheme);
+    const lines = md.render(40);
+    assert.ok(lines.length > 0, "Markdown should produce at least one line");
+    // At least one line should have visible content
+    const hasContent = lines.some((l) => visibleWidth(l) > 0);
+    assert.ok(hasContent, "At least one rendered line should have visible content");
+  });
+
+  it("Markdown component renders code blocks", () => {
+    const mdTheme = getMarkdownTheme();
+    const md = new Markdown("```ts\nconst x = 1;\n```", 1, 0, mdTheme);
+    const lines = md.render(40);
+    assert.ok(lines.length > 0);
+    const joined = lines.join("\n");
+    // The rendered output should contain the code content somewhere
+    assert.ok(joined.includes("const") || joined.includes("x"), "Code block content should be present");
+  });
+
+  it("Markdown component respects width constraint", () => {
+    const mdTheme = getMarkdownTheme();
+    const longContent = "This is a very long paragraph that should wrap when rendered at a narrow width constraint.";
+    const md = new Markdown(longContent, 1, 0, mdTheme);
+    const lines = md.render(30);
+    // All lines should respect the width
+    for (const line of lines) {
+      assert.ok(
+        visibleWidth(line) <= 30,
+        `Line exceeds width: "${line}" (visible: ${visibleWidth(line)})`,
+      );
+    }
+  });
+});
+
+// ─── Layout stability ─────────────────────────────────────────────────────────
+
+describe("layout stability", () => {
+  const MIN_PREVIEW_WIDTH = 30;
+  const MIN_OPTIONS_WIDTH = 30;
+  const DIVIDER_WIDTH = 3;
+
+  /** Mirrors questionHasAnyPreview() logic from interview-ui.ts */
+  function questionHasAnyPreview(options: QuestionOption[]): boolean {
+    return options.some((o) => o.preview != null && o.preview.trim().length > 0);
+  }
+
+  it("useSideBySide is true when ANY option has a preview (not just current)", () => {
+    const options: QuestionOption[] = [
+      { label: "A", description: "Has preview", preview: "# Hello" },
+      { label: "B", description: "No preview" },
+      { label: "C", description: "Also no preview" },
+    ];
+    const width = 100;
+    const useSideBySide = questionHasAnyPreview(options) && width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(useSideBySide, true, "side-by-side should activate when any option has preview");
+  });
+
+  it("useSideBySide is false when no options have a preview", () => {
+    const options: QuestionOption[] = [
+      { label: "A", description: "No preview" },
+      { label: "B", description: "No preview" },
+    ];
+    const useSideBySide = questionHasAnyPreview(options) && 100 >= 63;
+    assert.equal(useSideBySide, false);
+  });
+
+  it("PREVIEW_MAX_LINES produces constant side-by-side height", () => {
+    const PREVIEW_MAX_LINES = 20;
+    // Short and long content both produce exactly PREVIEW_MAX_LINES after cap+pad
+    for (const contentLen of [3, 10, 15, 30]) {
+      const capped = Math.min(contentLen, PREVIEW_MAX_LINES);
+      const padded = Math.max(capped, PREVIEW_MAX_LINES);
+      assert.equal(padded, PREVIEW_MAX_LINES, `content ${contentLen} should pad to ${PREVIEW_MAX_LINES}`);
+    }
+  });
+
+  it("total with PREVIEW_MAX_LINES fits in standard terminal (single-question)", () => {
+    const PREVIEW_MAX_LINES = 20;
+    const singleHeader = 1;  // bar only
+    const footer = 3;        // blank + hints + bar
+    const total = singleHeader + PREVIEW_MAX_LINES + footer;
+    assert.ok(total <= 24, `single-question total ${total} exceeds 24-row terminal`);
+  });
+});
+
+// ─── Preview layout constants ─────────────────────────────────────────────────
+
+describe("preview layout constraints", () => {
+  const MIN_PREVIEW_WIDTH = 30;
+  const MIN_OPTIONS_WIDTH = 30;
+  const DIVIDER_WIDTH = 3;
+  const PREVIEW_RATIO = 0.60;
+
+  it("minimum terminal width for preview = MIN_OPTIONS + MIN_PREVIEW + DIVIDER", () => {
+    const minWidth = MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH;
+    assert.equal(minWidth, 63);
+  });
+
+  it("at minimum width, both columns get their floor", () => {
+    const width = 63;
+    const previewWidth = Math.max(MIN_PREVIEW_WIDTH, Math.floor(width * PREVIEW_RATIO));
+    const leftWidth = Math.max(MIN_OPTIONS_WIDTH, width - previewWidth - DIVIDER_WIDTH);
+    assert.ok(previewWidth >= MIN_PREVIEW_WIDTH, `preview ${previewWidth} < min ${MIN_PREVIEW_WIDTH}`);
+    assert.ok(leftWidth >= MIN_OPTIONS_WIDTH, `options ${leftWidth} < min ${MIN_OPTIONS_WIDTH}`);
+  });
+
+  it("at wide terminal, preview ratio is approximately 60%", () => {
+    const width = 120;
+    const previewWidth = Math.max(MIN_PREVIEW_WIDTH, Math.floor(width * PREVIEW_RATIO));
+    const leftWidth = Math.max(MIN_OPTIONS_WIDTH, width - previewWidth - DIVIDER_WIDTH);
+    // Preview should be close to 60% of total
+    const actualRatio = previewWidth / width;
+    assert.ok(actualRatio >= 0.55 && actualRatio <= 0.65, `Ratio ${actualRatio} not near 0.60`);
+    assert.ok(leftWidth >= MIN_OPTIONS_WIDTH);
+  });
+
+  it("preview disabled when terminal is too narrow", () => {
+    const width = 62; // just under threshold
+    const canShow = width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(canShow, false);
+  });
+
+  it("preview enabled when terminal is exactly at threshold", () => {
+    const width = 63;
+    const canShow = width >= (MIN_OPTIONS_WIDTH + MIN_PREVIEW_WIDTH + DIVIDER_WIDTH);
+    assert.equal(canShow, true);
+  });
+});

package/src/resources/extensions/shared/tests/preview-layout.test.ts

@@ -0,0 +1,120 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { visibleWidth } from "@gsd/pi-tui";
+import { mergeSideBySide, padRight } from "../layout-utils.js";
+
+// ─── mergeSideBySide ──────────────────────────────────────────────────────────
+
+describe("mergeSideBySide", () => {
+  const plainDivider = " | ";
+
+  it("merges equal-length line arrays", () => {
+    const left = ["aaa", "bbb"];
+    const right = ["111", "222"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    // left padded to 6, then divider, then right
+    assert.ok(merged[0].includes("aaa"));
+    assert.ok(merged[0].includes("111"));
+    assert.ok(merged[1].includes("bbb"));
+    assert.ok(merged[1].includes("222"));
+  });
+
+  it("pads short left lines to leftWidth", () => {
+    const left = ["ab"];
+    const right = ["xy"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    // "ab" padded to 6 = "ab    ", then " | ", then "xy"
+    assert.ok(merged[0].startsWith("ab    "));
+  });
+
+  it("handles empty left array", () => {
+    const merged = mergeSideBySide([], ["aaa", "bbb"], 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    // Left side should be blank (just padding)
+    assert.ok(merged[0].startsWith("      "));
+  });
+
+  it("handles empty right array", () => {
+    const merged = mergeSideBySide(["aaa", "bbb"], [], 6, plainDivider, 80);
+    assert.equal(merged.length, 2);
+    assert.ok(merged[0].includes("aaa"));
+  });
+
+  it("handles both arrays empty", () => {
+    const merged = mergeSideBySide([], [], 6, plainDivider, 80);
+    assert.equal(merged.length, 0);
+  });
+
+  it("handles mismatched lengths — left longer", () => {
+    const left = ["a", "b", "c"];
+    const right = ["1"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 3);
+    assert.ok(merged[0].includes("1"));
+    // Lines 2 and 3 have empty right side
+    assert.ok(merged[2].includes("c"));
+  });
+
+  it("handles mismatched lengths — right longer", () => {
+    const left = ["a"];
+    const right = ["1", "2", "3"];
+    const merged = mergeSideBySide(left, right, 6, plainDivider, 80);
+    assert.equal(merged.length, 3);
+    assert.ok(merged[2].includes("3"));
+  });
+
+  it("truncates merged output to totalWidth", () => {
+    const left = ["aaaaaaaaaa"];  // 10 chars
+    const right = ["bbbbbbbbbb"]; // 10 chars
+    const merged = mergeSideBySide(left, right, 10, plainDivider, 15);
+    // Should be truncated to 15 visible chars
+    assert.ok(visibleWidth(merged[0]) <= 15);
+  });
+
+  it("handles ANSI-colored left content correctly", () => {
+    const red = "\x1b[31m";
+    const reset = "\x1b[0m";
+    const left = [`${red}hello${reset}`]; // visible: "hello" (5 chars)
+    const right = ["world"];
+    const merged = mergeSideBySide(left, right, 8, plainDivider, 80);
+    // "hello" is 5 visible chars, padded to 8 = 3 spaces of padding
+    // The ANSI codes don't count toward visible width
+    assert.ok(merged[0].includes(red));
+    assert.ok(merged[0].includes("world"));
+    // Verify padding is correct (8 visible chars on left side)
+    const beforeDivider = merged[0].split(" | ")[0];
+    assert.equal(visibleWidth(beforeDivider), 8);
+  });
+
+  it("handles ANSI-colored divider", () => {
+    const dim = "\x1b[2m";
+    const reset = "\x1b[0m";
+    const styledDivider = `${dim} │ ${reset}`;
+    const left = ["abc"];
+    const right = ["xyz"];
+    const merged = mergeSideBySide(left, right, 6, styledDivider, 80);
+    assert.equal(merged.length, 1);
+    assert.ok(merged[0].includes("abc"));
+    assert.ok(merged[0].includes("xyz"));
+  });
+});
+
+// ─── padRight with ANSI ───────────────────────────────────────────────────────
+
+describe("padRight with ANSI content", () => {
+  it("pads based on visible width, not string length", () => {
+    const red = "\x1b[31m";
+    const reset = "\x1b[0m";
+    const colored = `${red}hi${reset}`;
+    // colored.length >> 2, but visible width is 2
+    const padded = padRight(colored, 6);
+    assert.equal(visibleWidth(padded), 6);
+  });
+
+  it("does not over-pad plain text", () => {
+    const padded = padRight("hello", 5);
+    assert.equal(padded, "hello");
+    assert.equal(visibleWidth(padded), 5);
+  });
+});

package/src/resources/skills/create-workflow/SKILL.md

@@ -46,8 +46,32 @@ You are a workflow definition author. You help users create valid V1 YAML workfl
 
 **Output Location:**
 
-- Finished definitions go in `.gsd/workflow-defs/<name>.yaml`.
-- After writing, tell the user to validate with `/gsd workflow validate <name>`.
+- Project plugins: `.gsd/workflows/<name>.yaml` (preferred — checked into repo).
+- Global plugins: `~/.gsd/workflows/<name>.yaml` (private to the machine). Use
+  this when the user says "global" or "--global".
+- Legacy location `.gsd/workflow-defs/<name>.yaml` still works but is being
+  phased out — only write there if the user explicitly asks.
+- After writing, tell the user to validate with `/gsd workflow validate <name>`
+  and run with `/gsd workflow <name>`.
+
+**Execution mode:**
+
+Workflow plugins declare a `mode:` field in their top-level YAML (or
+`<template_meta>` block for markdown) that controls runtime behavior:
+
+- `oneshot` — prompt-only, no state, no artifact dir. For one-pass tasks
+  like reviews, reports, or one-off scripts. Default for YAML with a single
+  step when iteration isn't needed.
+- `yaml-step` — full engine with GRAPH.yaml, iterate, and verify. **Default
+  for YAML.** Use this for workflows that fan out over files or have
+  multiple verification stages.
+- `markdown-phase` — phased markdown-driven workflows with STATE.json and
+  phase-approval gates. For multi-session projects. Markdown-only.
+- `auto-milestone` — hooks into the full `/gsd auto` pipeline. Reserved
+  for the bundled `full-project` template; not normally authored by users.
+
+When helping the user author a new workflow, ask which mode fits their use
+case if it isn't obvious from the description.
 </essential_principles>
 
 <routing>
@@ -96,8 +120,11 @@ When assembling the final YAML:
 1. Use 2-space indentation consistently.
 2. Quote string values that contain special YAML characters (`:`, `{`, `}`, `[`, `]`, `#`).
 3. Always include `version: 1` as the first field.
-4. Order top-level fields: `version`, `name`, `description`, `params`, `steps`.
-5. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
-6. Write the file to `.gsd/workflow-defs/<name>.yaml`.
-7. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the definition."
+4. Order top-level fields: `version`, `name`, `mode`, `description`, `params`, `steps`.
+5. Include a `mode:` field (`oneshot` or `yaml-step`). Default to `yaml-step`.
+6. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
+7. Write to `.gsd/workflows/<name>.yaml` by default, or `~/.gsd/workflows/<name>.yaml`
+   when the user says "global" or passes `--global`.
+8. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the
+   definition, then `/gsd workflow <name>` to run it."
 </output_conventions>