npm - @ahmedalbarghouti/farq - Versions diffs - 0.0.3 → 0.1.0 - Mend

@ahmedalbarghouti/farq 0.0.3 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (43) hide show

package/README.md +51 -2
package/dist/concurrency.d.ts +2 -0
package/dist/concurrency.js +16 -0
package/dist/config.d.ts +16 -0
package/dist/config.js +25 -0
package/dist/git.d.ts +7 -3
package/dist/git.js +36 -27
package/dist/index.js +109 -30
package/dist/providers/claude.d.ts +1 -0
package/dist/providers/claude.js +49 -32
package/dist/providers/fake.d.ts +5 -2
package/dist/providers/fake.js +26 -15
package/dist/providers/index.d.ts +1 -1
package/dist/providers/index.js +1 -1
package/dist/schema.d.ts +40 -7
package/dist/schema.js +14 -1
package/dist/summarize.js +7 -0
package/dist/ui/index.d.ts +1 -0
package/dist/ui/index.js +1 -0
package/dist/ui/lines.d.ts +19 -1
package/dist/ui/lines.js +81 -39
package/dist/ui/logger.d.ts +9 -2
package/dist/ui/logger.js +15 -4
package/dist/ui/spinner.d.ts +15 -2
package/dist/ui/spinner.js +105 -22
package/dist/ui/theme.d.ts +1 -0
package/dist/ui/theme.js +3 -0
package/dist/visual/chrome.js +16 -0
package/dist/visual/cluster.d.ts +8 -2
package/dist/visual/cluster.js +36 -12
package/dist/visual/compose.d.ts +6 -1
package/dist/visual/compose.js +11 -28
package/dist/visual/css-scope.d.ts +6 -0
package/dist/visual/css-scope.js +162 -0
package/dist/visual/design.d.ts +103 -0
package/dist/visual/design.js +327 -0
package/dist/visual/diagram.d.ts +7 -0
package/dist/visual/diagram.js +36 -18
package/dist/visual/mockup.d.ts +15 -12
package/dist/visual/mockup.js +45 -26
package/dist/visual/pipeline.d.ts +30 -1
package/dist/visual/pipeline.js +71 -35
package/package.json +1 -1

package/dist/providers/fake.d.ts CHANGED Viewed

@@ -1,7 +1,10 @@
 import type { ChangeSummary } from "../schema.js";
 export declare const FAKE_SUMMARY: ChangeSummary;
-export declare const FAKE_BEFORE_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0;color:#444\">Total: $48.00</p>\n</main></body></html>";
-export declare const FAKE_AFTER_HTML = "<!doctype html><html><body style=\"font-family:system-ui;padding:24px;background:#f6f6f6\">\n<main style=\"max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd\">\n  <h1 style=\"font-size:18px;margin:0 0 8px\">Order #1042</h1>\n  <p style=\"margin:0 0 8px;color:#444\">Total: $48.00</p>\n  <p style=\"margin:0;color:#0a7\">Refund status: pending</p>\n</main></body></html>";
+export declare const FAKE_MOCKUP_CSS = ".page{padding:32px;background:var(--fq-surface)}\n.card{max-width:340px;padding:24px;background:var(--fq-surface-alt);border:1px solid var(--fq-border);border-radius:var(--fq-radius)}\n.card h1{margin:0 0 8px;font-family:var(--fq-font-display);font-size:20px}\n.card p{margin:0 0 8px;color:var(--fq-text-muted)}\n.card p.status{margin:0;color:var(--fq-positive)}";
+export declare const FAKE_BEFORE_BODY = "<div class=\"page\"><div class=\"card\"><h1>Order #1042</h1><p>Total: $48.00</p></div></div>";
+export declare const FAKE_AFTER_BODY = "<div class=\"page\"><div class=\"card\"><h1>Order #1042</h1><p>Total: $48.00</p><p class=\"status\">Refund status: pending</p></div></div>";
+export declare const FAKE_DIAGRAM_CSS = ".cols{display:flex;gap:24px}\n.col{flex:1;padding:16px;border:1px solid var(--fq-border);border-radius:var(--fq-radius)}\n.step{padding:8px 12px;margin-bottom:8px;background:var(--fq-surface-alt);border-radius:var(--fq-radius-sm)}\n.step--new{background:var(--fq-accent-soft);color:var(--fq-accent)}";
+export declare const FAKE_DIAGRAM_BODY = "<div class=\"cols\"><div class=\"col\"><div class=\"step\">Fetch order</div><div class=\"step\">Return payload</div></div><div class=\"col\"><div class=\"step\">Fetch order</div><div class=\"step step--new\">Attach refund status</div><div class=\"step\">Return payload</div></div></div>";
 export type CompleteOptions = {
     model?: string;
 };

package/dist/providers/fake.js CHANGED Viewed

@@ -18,25 +18,36 @@ export const FAKE_SUMMARY = {
     ],
     breaking_changes: [],
     visual_notes: "Show a simple status badge on the order card.",
+    visual_topics: [{ title: "Refund status on orders", item_indices: [0, 1] }],
 };
-export const FAKE_BEFORE_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
-<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
-  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
-  <p style="margin:0;color:#444">Total: $48.00</p>
-</main></body></html>`;
-export const FAKE_AFTER_HTML = `<!doctype html><html><body style="font-family:system-ui;padding:24px;background:#f6f6f6">
-<main style="max-width:420px;margin:auto;background:#fff;padding:16px;border:1px solid #ddd">
-  <h1 style="font-size:18px;margin:0 0 8px">Order #1042</h1>
-  <p style="margin:0 0 8px;color:#444">Total: $48.00</p>
-  <p style="margin:0;color:#0a7">Refund status: pending</p>
-</main></body></html>`;
+export const FAKE_MOCKUP_CSS = `.page{padding:32px;background:var(--fq-surface)}
+.card{max-width:340px;padding:24px;background:var(--fq-surface-alt);border:1px solid var(--fq-border);border-radius:var(--fq-radius)}
+.card h1{margin:0 0 8px;font-family:var(--fq-font-display);font-size:20px}
+.card p{margin:0 0 8px;color:var(--fq-text-muted)}
+.card p.status{margin:0;color:var(--fq-positive)}`;
+export const FAKE_BEFORE_BODY = `<div class="page"><div class="card"><h1>Order #1042</h1><p>Total: $48.00</p></div></div>`;
+export const FAKE_AFTER_BODY = `<div class="page"><div class="card"><h1>Order #1042</h1><p>Total: $48.00</p><p class="status">Refund status: pending</p></div></div>`;
+export const FAKE_DIAGRAM_CSS = `.cols{display:flex;gap:24px}
+.col{flex:1;padding:16px;border:1px solid var(--fq-border);border-radius:var(--fq-radius)}
+.step{padding:8px 12px;margin-bottom:8px;background:var(--fq-surface-alt);border-radius:var(--fq-radius-sm)}
+.step--new{background:var(--fq-accent-soft);color:var(--fq-accent)}`;
+export const FAKE_DIAGRAM_BODY = `<div class="cols"><div class="col"><div class="step">Fetch order</div><div class="step">Return payload</div></div><div class="col"><div class="step">Fetch order</div><div class="step step--new">Attach refund status</div><div class="step">Return payload</div></div></div>`;
 export async function complete(prompt, _options = {}) {
-    if (prompt.includes("before_html") || prompt.includes("feasible")) {
+    if (prompt.includes("before_body")) {
         return JSON.stringify({
             feasible: true,
-            before_html: FAKE_BEFORE_HTML,
-            after_html: FAKE_AFTER_HTML,
-            viewport: { width: 900, height: 700 },
+            css: FAKE_MOCKUP_CSS,
+            before_body: FAKE_BEFORE_BODY,
+            after_body: FAKE_AFTER_BODY,
+            stage_width: 620,
+        });
+    }
+    if (prompt.includes("flowchart")) {
+        return JSON.stringify({
+            feasible: true,
+            css: FAKE_DIAGRAM_CSS,
+            body: FAKE_DIAGRAM_BODY,
+            stage_width: 900,
         });
     }
     return JSON.stringify(FAKE_SUMMARY);

package/dist/providers/index.d.ts CHANGED Viewed

@@ -19,4 +19,4 @@ export declare function detectProviders(): Promise<{
 }>;
 export declare function resolveProvider(options?: ResolveProviderOptions): Promise<Provider>;
 export declare function getProvider(name: ProviderName): Provider;
-export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";
+export { FAKE_SUMMARY, FAKE_MOCKUP_CSS, FAKE_BEFORE_BODY, FAKE_AFTER_BODY, FAKE_DIAGRAM_CSS, FAKE_DIAGRAM_BODY, } from "./fake.js";

package/dist/providers/index.js CHANGED Viewed

@@ -37,4 +37,4 @@ export function getProvider(name) {
             return { name, complete: fake.complete };
     }
 }
-export { FAKE_SUMMARY, FAKE_BEFORE_HTML, FAKE_AFTER_HTML } from "./fake.js";
+export { FAKE_SUMMARY, FAKE_MOCKUP_CSS, FAKE_BEFORE_BODY, FAKE_AFTER_BODY, FAKE_DIAGRAM_CSS, FAKE_DIAGRAM_BODY, } from "./fake.js";

package/dist/schema.d.ts CHANGED Viewed

@@ -7,18 +7,32 @@ export declare const ChangeItemSchema: z.ZodObject<{
     why_it_matters: z.ZodOptional<z.ZodString>;
     files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    description: string;
     files: string[];
     category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
     title: string;
-    description: string;
     why_it_matters?: string | undefined;
 }, {
+    description: string;
     category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
     title: string;
-    description: string;
     files?: string[] | undefined;
     why_it_matters?: string | undefined;
 }>;
+/**
+ * Grouping of items into visual topics, returned by the same call that writes
+ * the summary so the visual pipeline does not need its own round-trip.
+ */
+export declare const VisualTopicSchema: z.ZodObject<{
+    title: z.ZodString;
+    item_indices: z.ZodArray<z.ZodNumber, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    item_indices: number[];
+}, {
+    title: string;
+    item_indices: number[];
+}>;
 export declare const ChangeSummarySchema: z.ZodObject<{
     headline: z.ZodString;
     overview: z.ZodString;
@@ -29,46 +43,65 @@ export declare const ChangeSummarySchema: z.ZodObject<{
         why_it_matters: z.ZodOptional<z.ZodString>;
         files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
+        description: string;
         files: string[];
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         why_it_matters?: string | undefined;
     }, {
+        description: string;
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         files?: string[] | undefined;
         why_it_matters?: string | undefined;
     }>, "many">;
     breaking_changes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     visual_notes: z.ZodOptional<z.ZodString>;
+    visual_topics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        item_indices: z.ZodArray<z.ZodNumber, "many">;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        item_indices: number[];
+    }, {
+        title: string;
+        item_indices: number[];
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     headline: string;
     overview: string;
     items: {
+        description: string;
         files: string[];
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         why_it_matters?: string | undefined;
     }[];
     breaking_changes: string[];
     visual_notes?: string | undefined;
+    visual_topics?: {
+        title: string;
+        item_indices: number[];
+    }[] | undefined;
 }, {
     headline: string;
     overview: string;
     items: {
+        description: string;
         category: "feature" | "fix" | "improvement" | "refactor" | "chore" | "docs" | "perf" | "security";
         title: string;
-        description: string;
         files?: string[] | undefined;
         why_it_matters?: string | undefined;
     }[];
     breaking_changes?: string[] | undefined;
     visual_notes?: string | undefined;
+    visual_topics?: {
+        title: string;
+        item_indices: number[];
+    }[] | undefined;
 }>;
 export type ChangeSummary = z.infer<typeof ChangeSummarySchema>;
 export type ChangeItem = z.infer<typeof ChangeItemSchema>;
+export type VisualTopicHint = z.infer<typeof VisualTopicSchema>;
 /** Compact schema description embedded in AI prompts. */
-export declare const CHANGE_SUMMARY_SCHEMA_PROMPT = "{\n  \"headline\": \"string <=140 \u2014 one-line summary (PR title)\",\n  \"overview\": \"string \u2014 1-3 sentences in requested tone\",\n  \"items\": [{\n    \"category\": \"feature|fix|improvement|refactor|chore|docs|perf|security\",\n    \"title\": \"string <=120\",\n    \"description\": \"string\",\n    \"why_it_matters\": \"string (optional; required for client tone)\",\n    \"files\": [\"string\"]\n  }],\n  \"breaking_changes\": [\"string\"],\n  \"visual_notes\": \"string (optional)\"\n}";
+export declare const CHANGE_SUMMARY_SCHEMA_PROMPT = "{\n  \"headline\": \"string <=140 \u2014 one-line summary (PR title)\",\n  \"overview\": \"string \u2014 1-3 sentences in requested tone\",\n  \"items\": [{\n    \"category\": \"feature|fix|improvement|refactor|chore|docs|perf|security\",\n    \"title\": \"string <=120\",\n    \"description\": \"string\",\n    \"why_it_matters\": \"string (optional; required for client tone)\",\n    \"files\": [\"string\"]\n  }],\n  \"breaking_changes\": [\"string\"],\n  \"visual_notes\": \"string (optional)\",\n  \"visual_topics\": [{\n    \"title\": \"string <=80 \u2014 human topic name\",\n    \"item_indices\": [0]\n  }]\n}";

package/dist/schema.js CHANGED Viewed

@@ -16,12 +16,21 @@ export const ChangeItemSchema = z.object({
     why_it_matters: z.string().min(1).optional(),
     files: z.array(z.string()).default([]),
 });
+/**
+ * Grouping of items into visual topics, returned by the same call that writes
+ * the summary so the visual pipeline does not need its own round-trip.
+ */
+export const VisualTopicSchema = z.object({
+    title: z.string().min(1).max(80),
+    item_indices: z.array(z.number().int().nonnegative()).min(1),
+});
 export const ChangeSummarySchema = z.object({
     headline: z.string().min(1).max(140),
     overview: z.string().min(1),
     items: z.array(ChangeItemSchema).min(1),
     breaking_changes: z.array(z.string()).default([]),
     visual_notes: z.string().min(1).optional(),
+    visual_topics: z.array(VisualTopicSchema).optional(),
 });
 /** Compact schema description embedded in AI prompts. */
 export const CHANGE_SUMMARY_SCHEMA_PROMPT = `{
@@ -35,5 +44,9 @@ export const CHANGE_SUMMARY_SCHEMA_PROMPT = `{
     "files": ["string"]
   }],
   "breaking_changes": ["string"],
-  "visual_notes": "string (optional)"
+  "visual_notes": "string (optional)",
+  "visual_topics": [{
+    "title": "string <=80 — human topic name",
+    "item_indices": [0]
+  }]
 }`;

package/dist/summarize.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { extractJson } from "./extract-json.js";
 import { CHANGE_SUMMARY_SCHEMA_PROMPT, ChangeSummarySchema, } from "./schema.js";
+import { MAX_VISUAL_TOPICS } from "./visual/cluster.js";
 export class SummarizeError extends Error {
     exitCode = 2;
     constructor(message) {
@@ -59,6 +60,12 @@ Rules:
 - Report only what the diff shows. Do not invent work.
 - ${toneRules}
 ${convention}
+visual_topics — how the items get grouped into before/after visuals:
+- Every item index must appear in exactly one topic. Use 0-based indices into your own items array.
+- If all items advance the SAME feature or story, return exactly ONE topic containing every index, even across many files, tests, docs and plumbing.
+- Only split when a reviewer would call them separate product changes (say, a UI redesign AND an unrelated billing API).
+- At most ${MAX_VISUAL_TOPICS} topics. Fewer is better; one is right when unsure.
 Schema:
 ${CHANGE_SUMMARY_SCHEMA_PROMPT}

package/dist/ui/index.d.ts CHANGED Viewed

@@ -1,2 +1,3 @@
 export { createUi, type Ui } from "./logger.js";
+export { labelFor, linesFor, type LineBank } from "./lines.js";
 export { brand, isInteractive } from "./theme.js";

package/dist/ui/index.js CHANGED Viewed

@@ -1,2 +1,3 @@
 export { createUi } from "./logger.js";
+export { labelFor, linesFor } from "./lines.js";
 export { brand, isInteractive } from "./theme.js";

package/dist/ui/lines.d.ts CHANGED Viewed

@@ -1,3 +1,21 @@
 import type { ProviderName } from "../config.js";
-export type LineBank = "summarize" | "visual" | "open" | "diff";
+/**
+ * Rotating status lines. `{p}` is replaced with the provider name so a line
+ * always says who is doing the work. Keep templates <= 37 chars so the longest
+ * provider name still fits the one-line spinner.
+ */
+declare const BANKS: {
+    diff: string[];
+    summarize: string[];
+    topics: string[];
+    mockup: string[];
+    diagram: string[];
+    shoot: string[];
+    visual: string[];
+    open: string[];
+};
+export type LineBank = keyof typeof BANKS;
 export declare function linesFor(bank: LineBank, provider?: ProviderName): string[];
+/** Short, honest name for the stage — the witty line sits next to it. */
+export declare function labelFor(bank: LineBank): string;
+export {};

package/dist/ui/lines.js CHANGED Viewed

@@ -1,48 +1,90 @@
-const SUMMARIZE = {
-    claude: [
-        "claude is reading the diff…",
-        "claude is grouping the mess…",
-        "claude is writing the blurb…",
-    ],
-    opencode: [
-        "opencode is reading the diff…",
-        "opencode is grouping the mess…",
-        "opencode is writing the blurb…",
-    ],
-    fake: [
-        "fake is vibing on hard mode…",
-        "fake is inventing nothing new…",
-        "fake is shipping canned vibes…",
+/**
+ * Rotating status lines. `{p}` is replaced with the provider name so a line
+ * always says who is doing the work. Keep templates <= 37 chars so the longest
+ * provider name still fits the one-line spinner.
+ */
+const BANKS = {
+    diff: [
+        "gathering the diff…",
+        "asking git politely…",
+        "reading what you actually did…",
+        "diffing against the merge base…",
+        "counting the damage…",
     ],
-};
-const VISUAL = {
-    claude: [
-        "claude is sketching a mockup…",
-        "claude is boxing a flowchart…",
-        "chrome is taking the shot…",
+    summarize: [
+        "{p} is reading the diff…",
+        "{p} is grouping the mess…",
+        "{p} is finding the story…",
+        "{p} is naming things (hard part)…",
+        "{p} is deciding what matters…",
+        "{p} is skipping the boring parts…",
+        "{p} is drafting your PR title…",
+        "{p} is writing the blurb…",
     ],
-    opencode: [
-        "opencode is sketching a mockup…",
-        "opencode is boxing a flowchart…",
-        "chrome is taking the shot…",
+    topics: [
+        "planning the visuals…",
+        "splitting the story into scenes…",
+        "deciding how many pictures…",
+        "grouping changes into topics…",
+    ],
+    mockup: [
+        "{p} is sketching the before…",
+        "{p} is sketching the after…",
+        "{p} is laying out the mockup…",
+        "{p} is writing placeholder copy…",
+        "{p} is obeying the design tokens…",
+        "{p} is resisting a redesign…",
+        "{p} is measuring the spacing…",
     ],
-    fake: [
-        "fake is drawing boxes…",
-        "fake is pretending to design…",
+    diagram: [
+        "{p} is boxing a flowchart…",
+        "{p} is drawing arrows…",
+        "{p} is explaining it with boxes…",
+        "{p} is keeping it conceptual…",
+        "{p} is deleting a wall of text…",
+    ],
+    shoot: [
         "chrome is taking the shot…",
+        "chrome is scaling it to fit…",
+        "waiting on headless chrome…",
+        "pressing the shutter…",
+    ],
+    visual: [
+        "{p} is drawing the difference…",
+        "{p} is picking a composition…",
+        "chrome is warming up…",
+        "making the change look obvious…",
+    ],
+    open: [
+        "talking to gh…",
+        "filling the PR template…",
+        "uploading the visuals…",
+        "shipping the PR body…",
+        "almost there…",
     ],
 };
-const OPEN = [
-    "talking to gh…",
-    "shipping the PR body…",
-    "almost there…",
-];
 export function linesFor(bank, provider) {
-    if (bank === "diff") {
-        return ["gathering the diff…", "asking git politely…"];
+    const name = provider ?? "claude";
+    return BANKS[bank].map((line) => line.replaceAll("{p}", name));
+}
+/** Short, honest name for the stage — the witty line sits next to it. */
+export function labelFor(bank) {
+    switch (bank) {
+        case "diff":
+            return "diff";
+        case "summarize":
+            return "summary";
+        case "topics":
+            return "planning";
+        case "mockup":
+            return "mockup";
+        case "diagram":
+            return "diagram";
+        case "shoot":
+            return "capture";
+        case "visual":
+            return "visuals";
+        case "open":
+            return "pull request";
     }
-    if (bank === "open")
-        return OPEN;
-    const p = provider ?? "claude";
-    return bank === "summarize" ? SUMMARIZE[p] : VISUAL[p];
 }

package/dist/ui/logger.d.ts CHANGED Viewed

@@ -1,11 +1,18 @@
 import type { ProviderName } from "../config.js";
 import { type LineBank } from "./lines.js";
 import { type SpinnerHandle } from "./spinner.js";
+export type StageOptions = {
+    provider?: ProviderName;
+    /** Override the stage label shown before the witty line. */
+    label?: string;
+};
 export type Ui = {
+    /** Declare how many stages this run will have, so steps read as [2/4]. */
+    plan: (totalSteps: number) => void;
     /** Plain note (no spinner). */
     note: (text: string) => void;
-    /** Start a spinning stage with optional rotating witty lines. */
-    stage: (bank: LineBank, provider?: ProviderName) => SpinnerHandle;
+    /** Start a numbered stage with rotating witty lines. */
+    stage: (bank: LineBank, options?: StageOptions | ProviderName) => SpinnerHandle;
     error: (text: string) => void;
     success: (text: string) => void;
 };

package/dist/ui/logger.js CHANGED Viewed

@@ -1,14 +1,25 @@
-import { linesFor } from "./lines.js";
+import { labelFor, linesFor } from "./lines.js";
 import { startSpinner } from "./spinner.js";
 import { brand, fail, muted, ok } from "./theme.js";
 export function createUi() {
+    let total = 0;
+    let step = 0;
     return {
+        plan(totalSteps) {
+            total = Math.max(0, Math.floor(totalSteps));
+            step = 0;
+        },
         note(text) {
             process.stderr.write(`${brand()} ${muted(text)}\n`);
         },
-        stage(bank, provider) {
-            const lines = linesFor(bank, provider);
-            return startSpinner(lines[0] ?? "working…", lines);
+        stage(bank, options) {
+            const opts = typeof options === "string" ? { provider: options } : (options ?? {});
+            step++;
+            return startSpinner({
+                lines: linesFor(bank, opts.provider),
+                label: opts.label ?? labelFor(bank),
+                step: total > 0 ? { index: Math.min(step, total), total } : undefined,
+            });
         },
         error(text) {
             process.stderr.write(`${brand()} ${fail(text)}\n`);

package/dist/ui/spinner.d.ts CHANGED Viewed

@@ -1,7 +1,20 @@
 export type SpinnerHandle = {
-    update: (text: string) => void;
+    /** Replace the stage label (rarely needed). */
+    update: (label: string) => void;
+    /** Swap the rotating witty lines mid-stage, e.g. summarize → mockup. */
+    setLines: (lines: string[]) => void;
+    /** Concrete sub-stage status shown after the witty line. */
+    detail: (text: string | null) => void;
     succeed: (text: string) => void;
     fail: (text: string) => void;
     stop: () => void;
 };
-export declare function startSpinner(initial: string, rotateLines?: string[]): SpinnerHandle;
+export type SpinnerOptions = {
+    lines: string[];
+    label?: string;
+    step?: {
+        index: number;
+        total: number;
+    };
+};
+export declare function startSpinner(options: SpinnerOptions): SpinnerHandle;

package/dist/ui/spinner.js CHANGED Viewed

@@ -1,46 +1,86 @@
-import { brand, accent, isInteractive, muted, ok, fail } from "./theme.js";
+import { accent, brand, dim, fail, isInteractive, muted, ok } from "./theme.js";
 const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-export function startSpinner(initial, rotateLines) {
+const FRAME_MS = 80;
+const ROTATE_MS = 2600;
+/** Only surface a timer once a stage is slow enough to feel slow. */
+const ELAPSED_AFTER_MS = 3000;
+export function startSpinner(options) {
     const interactive = isInteractive();
-    let text = initial;
-    let i = 0;
+    const started = Date.now();
+    let label = options.label ?? "working";
+    let lines = rotateOrder(options.lines);
     let lineIdx = 0;
+    let detailText = null;
+    let frame = 0;
     let timer = null;
     let lineTimer = null;
     let stopped = false;
+    let lastStatic = "";
+    const stepTag = options.step
+        ? `[${options.step.index}/${options.step.total}] `
+        : "";
+    const elapsedSeconds = () => (Date.now() - started) / 1000;
+    const compose = () => {
+        const parts = [lines[lineIdx] ?? label];
+        if (detailText)
+            parts.push(detailText);
+        const elapsed = Date.now() - started >= ELAPSED_AFTER_MS
+            ? `${Math.round(elapsedSeconds())}s`
+            : "";
+        const body = parts.join(dim(" · "));
+        const tail = elapsed ? `${dim(" · ")}${dim(elapsed)}` : "";
+        return `${accent(stepTag)}${label}${dim(" · ")}${muted(body)}${tail}`;
+    };
     const render = () => {
         if (!interactive || stopped)
             return;
-        const frame = accent(FRAMES[i % FRAMES.length]);
-        process.stderr.write(`\r\x1b[2K${brand()} ${frame} ${text}`);
-        i++;
+        const line = `${brand()} ${accent(FRAMES[frame % FRAMES.length])} ${compose()}`;
+        process.stderr.write(`\r\x1b[2K${truncate(line)}`);
+        frame++;
+    };
+    const printStatic = () => {
+        const next = detailText ? `${label} · ${detailText}` : label;
+        if (next === lastStatic)
+            return;
+        lastStatic = next;
+        process.stderr.write(`${brand()} ${muted(`${stepTag}${next}`)}\n`);
     };
     if (interactive) {
         render();
-        timer = setInterval(render, 80);
-        if (rotateLines && rotateLines.length > 1) {
+        timer = setInterval(render, FRAME_MS);
+        if (lines.length > 1) {
             lineTimer = setInterval(() => {
-                lineIdx = (lineIdx + 1) % rotateLines.length;
-                text = rotateLines[lineIdx];
-            }, 2000);
+                lineIdx = (lineIdx + 1) % lines.length;
+            }, ROTATE_MS);
         }
     }
     else {
-        process.stderr.write(`${brand()} ${muted(text)}\n`);
+        printStatic();
     }
-    return {
+    const handle = {
         update(next) {
-            text = next;
+            label = next;
+            if (!interactive)
+                printStatic();
+        },
+        setLines(next) {
+            if (next.length === 0)
+                return;
+            lines = rotateOrder(next);
+            lineIdx = 0;
+        },
+        detail(text) {
+            detailText = text && text.trim() ? text.trim() : null;
             if (!interactive)
-                process.stderr.write(`${brand()} ${muted(text)}\n`);
+                printStatic();
         },
-        succeed(next) {
-            this.stop();
-            process.stderr.write(`${brand()} ${ok(next)}\n`);
+        succeed(text) {
+            handle.stop();
+            process.stderr.write(`${brand()} ${ok(text)}${dim(` ${formatDuration(elapsedSeconds())}`)}\n`);
         },
-        fail(next) {
-            this.stop();
-            process.stderr.write(`${brand()} ${fail(next)}\n`);
+        fail(text) {
+            handle.stop();
+            process.stderr.write(`${brand()} ${fail(text)}\n`);
         },
         stop() {
             if (stopped)
@@ -54,4 +94,47 @@ export function startSpinner(initial, rotateLines) {
                 process.stderr.write("\r\x1b[2K");
         },
     };
+    return handle;
+}
+function formatDuration(seconds) {
+    if (seconds < 10)
+        return `${seconds.toFixed(1)}s`;
+    if (seconds < 60)
+        return `${Math.round(seconds)}s`;
+    const mins = Math.floor(seconds / 60);
+    return `${mins}m${String(Math.round(seconds % 60)).padStart(2, "0")}s`;
+}
+/** Keep the first line stable, shuffle the rest so reruns feel different. */
+function rotateOrder(lines) {
+    if (lines.length < 3)
+        return [...lines];
+    const [head, ...tail] = lines;
+    for (let i = tail.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [tail[i], tail[j]] = [tail[j], tail[i]];
+    }
+    return [head, ...tail];
+}
+/** Trim to the terminal width, ignoring ANSI escapes when measuring. */
+function truncate(line) {
+    const columns = process.stderr.columns ?? 0;
+    if (!columns || columns < 20)
+        return line;
+    const max = columns - 1;
+    let visible = 0;
+    let i = 0;
+    while (i < line.length) {
+        if (line[i] === "\x1b") {
+            const end = line.indexOf("m", i);
+            if (end === -1)
+                break;
+            i = end + 1;
+            continue;
+        }
+        if (visible === max)
+            return `${line.slice(0, i)}…\x1b[0m`;
+        visible++;
+        i++;
+    }
+    return line;
 }

package/dist/ui/theme.d.ts CHANGED Viewed

@@ -3,4 +3,5 @@ export declare function accent(text: string): string;
 export declare function ok(text: string): string;
 export declare function fail(text: string): string;
 export declare function muted(text: string): string;
+export declare function dim(text: string): string;
 export declare function isInteractive(): boolean;