@xdelivered/emberflow 0.2.0

package/src/components/WelcomeDialog.test.tsx

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { WelcomeChecklist } from './WelcomeDialog';
+import type { SetupStatus } from '../store/setupClient';
+
+/** A pristine, just-initialized project: no agent, no environments, no skills,
+ *  only the hello example op. */
+const FRESH: SetupStatus = {
+  agents: [],
+  environments: { configured: false, count: 0, protectedCount: 0, anyAuthConfigured: false },
+  skills: { claude: false, codex: false },
+  language: 'typescript',
+  ops: { count: 1, onlyHello: true },
+  servingMode: 'mock',
+  infrastructure: { present: false },
+};
+
+/** A project that's been set up: agent on PATH, environments + auth, skills
+ *  installed, infrastructure scouted, several ops. */
+const CONFIGURED: SetupStatus = {
+  agents: [
+    { kind: 'claude', version: '2.1.0' },
+    { kind: 'codex', version: '0.5.3' },
+  ],
+  environments: { configured: true, count: 2, protectedCount: 1, anyAuthConfigured: true },
+  skills: { claude: true, codex: false },
+  language: 'typescript',
+  ops: { count: 4, onlyHello: false },
+  servingMode: 'real',
+  infrastructure: { present: true, itemCount: 3 },
+};
+
+const html = (status: SetupStatus): string =>
+  renderToStaticMarkup(<WelcomeChecklist status={status} />);
+
+describe('WelcomeChecklist', () => {
+  it('renders every checklist row', () => {
+    const out = html(FRESH);
+    for (const title of [
+      'Coding agent detected',
+      'Environments configured',
+      'Secrets &amp; auth',
+      'Agent skills installed',
+      'Infrastructure scouted',
+      'First operation',
+    ]) {
+      expect(out).toContain(title);
+    }
+  });
+
+  it('fresh project: shows the install hint and no completed rows', () => {
+    const out = html(FRESH);
+    // Skills-missing hint is the copyable init command, no action button.
+    expect(out).toContain('npx emberflow init --local --no-launch');
+    expect(out).toContain('None detected on PATH');
+    // Nothing is done yet — no "done" glyph.
+    expect(out).not.toContain('aria-label="done"');
+  });
+
+  it('fresh project: the scout button is disabled without an agent', () => {
+    const out = html(FRESH);
+    // The Scout button carries the "detect an agent first" tooltip and is disabled.
+    expect(out).toContain('Detect a coding agent first');
+    expect(out).toMatch(/Scout/);
+    expect(out).toContain('disabled');
+  });
+
+  it('configured project: shows completed rows and agent versions', () => {
+    const out = html(CONFIGURED);
+    expect(out).toContain('aria-label="done"');
+    expect(out).toContain('claude 2.1.0');
+    expect(out).toContain('codex 0.5.3');
+    expect(out).toContain('2 environments, 1 protected');
+    // Skills present → no install hint.
+    expect(out).not.toContain('npx emberflow init');
+  });
+
+  it('configured project: scout is enabled (agent present)', () => {
+    const out = html(CONFIGURED);
+    expect(out).not.toContain('Detect a coding agent first');
+  });
+
+  it('two agents + onChooseAgent: renders the picker with the chosen agent pressed', () => {
+    const out = renderToStaticMarkup(
+      <WelcomeChecklist status={CONFIGURED} chosenAgent="codex" onChooseAgent={() => {}} />,
+    );
+    expect(out).toContain('Choose coding agent');
+    expect(out).toContain('Both detected');
+    // Codex is the active choice; Claude is not.
+    expect(out).toMatch(/aria-pressed="true"[^>]*>Codex/);
+    expect(out).toMatch(/aria-pressed="false"[^>]*>Claude/);
+  });
+
+  it('single agent: no picker even when onChooseAgent is provided', () => {
+    const oneAgent: SetupStatus = { ...CONFIGURED, agents: [{ kind: 'claude', version: '2.1.0' }] };
+    const out = renderToStaticMarkup(
+      <WelcomeChecklist status={oneAgent} onChooseAgent={() => {}} />,
+    );
+    expect(out).not.toContain('Choose coding agent');
+    expect(out).toContain('claude 2.1.0');
+  });
+
+  it('shows checklist progress', () => {
+    expect(html(FRESH)).toContain('0/6 done');
+    expect(html(CONFIGURED)).toContain('6/6 done');
+  });
+});

package/src/components/WelcomeDialog.tsx

@@ -0,0 +1,412 @@
+import { useEffect, useState } from 'react';
+import {
+  CheckCircle2Icon,
+  CheckIcon,
+  CircleIcon,
+  CopyIcon,
+  MinusCircleIcon,
+  SparklesIcon,
+} from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/components/ui/dialog';
+import { EnvironmentsDialog } from './EnvironmentsDialog';
+import { useBuilderStore } from '../store/builderStore';
+import { setupProgress, type SetupStatus } from '../store/setupClient';
+import type { AgentKind } from '../store/agentClient';
+
+const AGENT_LABELS: Record<AgentKind, string> = {
+  codex: 'Codex',
+  claude: 'Claude',
+};
+
+const WELCOME_DISMISSED_KEY = 'emberflow.welcome.dismissed';
+/** Re-run this exact command to (re)install the agent skills only. */
+const SKILLS_INSTALL_COMMAND = 'npx emberflow init --local --no-launch';
+
+type RowStatus = 'complete' | 'incomplete' | 'unavailable';
+
+function StatusGlyph({ status }: { status: RowStatus }) {
+  if (status === 'complete') {
+    return <CheckCircle2Icon className="mt-0.5 size-4 shrink-0 text-success" aria-label="done" />;
+  }
+  if (status === 'unavailable') {
+    return (
+      <MinusCircleIcon
+        className="mt-0.5 size-4 shrink-0 text-muted-foreground/30"
+        aria-label="not yet available"
+      />
+    );
+  }
+  return (
+    <CircleIcon
+      className="mt-0.5 size-4 shrink-0 text-muted-foreground/50"
+      aria-label="to do"
+    />
+  );
+}
+
+function SectionTitle({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="text-[10px] font-medium uppercase tracking-widest text-muted-foreground">
+      {children}
+    </div>
+  );
+}
+
+function ChecklistRow({
+  status,
+  title,
+  detail,
+  action,
+  children,
+}: {
+  status: RowStatus;
+  title: string;
+  detail: string;
+  action?: React.ReactNode;
+  children?: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-start gap-2.5 rounded-md border border-border/70 px-2.5 py-2">
+      <StatusGlyph status={status} />
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <span className="text-[12.5px] font-medium leading-tight">{title}</span>
+        <span className="text-[11px] leading-snug text-muted-foreground">{detail}</span>
+        {children}
+      </div>
+      {action && <div className="shrink-0 self-center">{action}</div>}
+    </div>
+  );
+}
+
+function CopyCommand({ command }: { command: string }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        void navigator.clipboard?.writeText(command);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1500);
+      }}
+      title="Copy to clipboard"
+      className="mt-0.5 flex items-center gap-2 self-start rounded-md border border-border bg-secondary/40 px-2 py-1 font-mono text-[11px] text-foreground/90 transition-colors hover:bg-secondary"
+    >
+      <code>{command}</code>
+      {copied ? (
+        <CheckIcon className="size-3 text-success" />
+      ) : (
+        <CopyIcon className="size-3 text-muted-foreground" />
+      )}
+    </button>
+  );
+}
+
+export interface WelcomeChecklistActions {
+  onOpenSettings: () => void;
+  onSetupEnvironments: () => void;
+  onOpenEnvironments: () => void;
+  onOpenHelloOp: () => void;
+  onScoutInfrastructure: () => void;
+}
+
+const NOOP_ACTIONS: WelcomeChecklistActions = {
+  onOpenSettings: () => {},
+  onSetupEnvironments: () => {},
+  onOpenEnvironments: () => {},
+  onOpenHelloOp: () => {},
+  onScoutInfrastructure: () => {},
+};
+
+/**
+ * Presentational checklist rendered from a resolved `/setup-status`. Split out
+ * from the dialog wrapper (which owns fetch/open state) so it renders purely
+ * from props — the component test drives it across fresh/configured/no-agent
+ * states without a live runner.
+ */
+export function WelcomeChecklist({
+  status,
+  actions = NOOP_ACTIONS,
+  chosenAgent,
+  onChooseAgent,
+}: {
+  status: SetupStatus;
+  actions?: WelcomeChecklistActions;
+  /** The user's preferred agent (from Settings); defaults to the first detected. */
+  chosenAgent?: AgentKind;
+  onChooseAgent?: (kind: AgentKind) => void;
+}) {
+  const { agents, environments, skills, ops, infrastructure } = status;
+  const hasAgent = agents.length > 0;
+  const skillsInstalled = skills.claude || skills.codex;
+  // With more than one agent CLI on PATH the row becomes a choice, not a fact.
+  const multipleAgents = agents.length > 1 && onChooseAgent !== undefined;
+  const activeAgent = chosenAgent ?? agents[0]?.kind;
+
+  const agentDetail = hasAgent
+    ? multipleAgents
+      ? 'Both detected — pick which one builds for you (changeable in Settings).'
+      : agents.map((a) => `${a.kind}${a.version ? ` ${a.version}` : ''}`).join(', ')
+    : 'None detected on PATH — install codex or claude to let the agent build for you.';
+
+  const envDetail = environments.configured
+    ? `${environments.count} environment${environments.count === 1 ? '' : 's'}` +
+      (environments.protectedCount > 0 ? `, ${environments.protectedCount} protected` : '')
+    : "You're in Mock — nothing real is touched. Set up environments to point runs at real systems.";
+
+  const secretsStatus: RowStatus = !environments.configured
+    ? 'unavailable'
+    : environments.anyAuthConfigured
+      ? 'complete'
+      : 'incomplete';
+  const secretsDetail = !environments.configured
+    ? 'Configure environments first — secrets and auth live per environment.'
+    : environments.anyAuthConfigured
+      ? 'Auth configured on at least one environment.'
+      : 'Add the secrets and login your operations need.';
+
+  const progress = setupProgress(status);
+
+  return (
+    <div className="space-y-2.5">
+      <div className="flex items-baseline justify-between">
+        <SectionTitle>Setup checklist</SectionTitle>
+        <span className="text-[10.5px] tabular-nums text-muted-foreground">
+          {progress.done}/{progress.total} done
+        </span>
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <ChecklistRow
+          status={hasAgent ? 'complete' : 'incomplete'}
+          title="Coding agent detected"
+          detail={agentDetail}
+          action={
+            <Button variant="outline" size="sm" onClick={actions.onOpenSettings}>
+              Settings
+            </Button>
+          }
+        >
+          {multipleAgents && (
+            <div className="mt-0.5 flex gap-1 self-start" role="group" aria-label="Choose coding agent">
+              {agents.map(({ kind, version }) => (
+                <button
+                  key={kind}
+                  type="button"
+                  onClick={() => onChooseAgent(kind)}
+                  aria-pressed={activeAgent === kind}
+                  className={cn(
+                    'cursor-pointer rounded-md border px-2 py-1 text-[11.5px] transition-colors',
+                    activeAgent === kind
+                      ? 'border-ring bg-secondary/60 font-medium text-foreground'
+                      : 'border-border text-muted-foreground hover:text-foreground',
+                  )}
+                >
+                  {AGENT_LABELS[kind]}
+                  {version ? <span className="ml-1 font-normal text-muted-foreground">{version}</span> : null}
+                </button>
+              ))}
+            </div>
+          )}
+        </ChecklistRow>
+
+        <ChecklistRow
+          status={environments.configured ? 'complete' : 'incomplete'}
+          title="Environments configured"
+          detail={envDetail}
+          action={
+            <div className="flex flex-col items-end gap-1">
+              <Button size="sm" onClick={actions.onSetupEnvironments}>
+                <SparklesIcon className="size-3.5" />
+                Set up with AI
+              </Button>
+              <button
+                type="button"
+                onClick={actions.onOpenEnvironments}
+                className="text-[10.5px] text-muted-foreground underline-offset-2 hover:text-foreground hover:underline"
+              >
+                Manage manually
+              </button>
+            </div>
+          }
+        />
+
+        <ChecklistRow
+          status={secretsStatus}
+          title="Secrets & auth"
+          detail={secretsDetail}
+          action={
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={!environments.configured}
+              onClick={actions.onOpenEnvironments}
+            >
+              Open
+            </Button>
+          }
+        />
+
+        <ChecklistRow
+          status={skillsInstalled ? 'complete' : 'incomplete'}
+          title="Agent skills installed"
+          detail={
+            skillsInstalled
+              ? 'emberflow-basics is installed for your agent.'
+              : 'Installed automatically by emberflow init — this project doesn’t have them yet. Add them (skills only, nothing else changes):'
+          }
+        >
+          {!skillsInstalled && <CopyCommand command={SKILLS_INSTALL_COMMAND} />}
+        </ChecklistRow>
+
+        <ChecklistRow
+          status={infrastructure.present ? 'complete' : 'incomplete'}
+          title="Infrastructure scouted"
+          detail={
+            infrastructure.present
+              ? `${infrastructure.itemCount ?? 0} item${infrastructure.itemCount === 1 ? '' : 's'} discovered.`
+              : 'Have the agent scan this project for databases, APIs and providers it already uses.'
+          }
+          action={
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={!hasAgent}
+              title={hasAgent ? undefined : 'Detect a coding agent first'}
+              onClick={actions.onScoutInfrastructure}
+            >
+              <SparklesIcon className="size-3.5" />
+              Scout
+            </Button>
+          }
+        />
+
+        <ChecklistRow
+          status={ops.count > 1 ? 'complete' : 'incomplete'}
+          title="First operation"
+          detail={
+            ops.count > 1
+              ? "You've built beyond the hello example."
+              : 'Only the hello example so far — open it to see how an operation is built.'
+          }
+          action={
+            <Button variant="outline" size="sm" onClick={actions.onOpenHelloOp}>
+              Open hello op
+            </Button>
+          }
+        />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * First-run Welcome/Setup dialog. Mounted once (in the Toolbar). Fetches
+ * `/setup-status` on mount to decide whether to auto-open on a fresh project,
+ * and again whenever it's opened so the rows reflect the latest state. Always
+ * reachable from the Toolbar's Setup button (via the store's `welcomeOpen`).
+ */
+export function WelcomeDialog() {
+  const welcomeOpen = useBuilderStore((s) => s.welcomeOpen);
+  const setWelcomeOpen = useBuilderStore((s) => s.setWelcomeOpen);
+  const openSettingsFromWelcome = useBuilderStore((s) => s.openSettingsFromWelcome);
+  const beginEnvironmentSetup = useBuilderStore((s) => s.beginEnvironmentSetup);
+  const beginInfrastructureScout = useBuilderStore((s) => s.beginInfrastructureScout);
+  const switchWorkflow = useBuilderStore((s) => s.switchWorkflow);
+  const status = useBuilderStore((s) => s.setupStatus);
+  const refreshSetupStatus = useBuilderStore((s) => s.refreshSetupStatus);
+  const agentChoice = useBuilderStore((s) => s.agentChoice);
+  const setAgentChoice = useBuilderStore((s) => s.setAgentChoice);
+  const [envDialogOpen, setEnvDialogOpen] = useState(false);
+
+  // Mount: fetch once and auto-open on a fresh, undismissed project.
+  useEffect(() => {
+    let cancelled = false;
+    void refreshSetupStatus().then((s) => {
+      if (cancelled || !s) return;
+      const dismissed =
+        typeof localStorage !== 'undefined' && localStorage.getItem(WELCOME_DISMISSED_KEY) === '1';
+      if (s.ops.onlyHello && !s.environments.configured && !dismissed) {
+        setWelcomeOpen(true);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+    // Mount-only: auto-open is a one-shot boot decision.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Refresh the rows every time the dialog opens (e.g. from the StatusBar chip).
+  useEffect(() => {
+    if (!welcomeOpen) return;
+    void refreshSetupStatus();
+  }, [welcomeOpen, refreshSetupStatus]);
+
+  /** A user-driven close (X / overlay / esc / Dismiss) records the dismissal so
+   *  the dialog never auto-opens again; navigational actions close without it. */
+  const dismiss = () => {
+    setWelcomeOpen(false);
+    if (typeof localStorage !== 'undefined') localStorage.setItem(WELCOME_DISMISSED_KEY, '1');
+  };
+
+  const actions: WelcomeChecklistActions = {
+    onOpenSettings: openSettingsFromWelcome,
+    onSetupEnvironments: () => {
+      setWelcomeOpen(false);
+      beginEnvironmentSetup();
+    },
+    onOpenEnvironments: () => {
+      setWelcomeOpen(false);
+      setEnvDialogOpen(true);
+    },
+    onOpenHelloOp: () => {
+      setWelcomeOpen(false);
+      switchWorkflow('default/hello');
+    },
+    onScoutInfrastructure: () => {
+      setWelcomeOpen(false);
+      beginInfrastructureScout();
+    },
+  };
+
+  return (
+    <>
+      <Dialog open={welcomeOpen} onOpenChange={(o) => (o ? setWelcomeOpen(true) : dismiss())}>
+        <DialogContent className="max-w-lg">
+          <DialogTitle>Welcome to Emberflow</DialogTitle>
+          <DialogDescription>
+            A few steps to get this project ready to build and run. Everything here is optional —
+            you can revisit it any time from the toolbar.
+          </DialogDescription>
+          {status ? (
+            <WelcomeChecklist
+              status={status}
+              actions={actions}
+              chosenAgent={agentChoice.agent}
+              onChooseAgent={(kind) => setAgentChoice({ ...agentChoice, agent: kind })}
+            />
+          ) : (
+            <div className="py-6 text-center text-[12px] text-muted-foreground">
+              Checking your project…
+            </div>
+          )}
+          <div className="flex justify-end">
+            <Button variant="ghost" size="sm" onClick={dismiss}>
+              Dismiss
+            </Button>
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      <EnvironmentsDialog
+        open={envDialogOpen}
+        onOpenChange={setEnvDialogOpen}
+        onBack={() => {
+          setEnvDialogOpen(false);
+          setWelcomeOpen(true);
+        }}
+      />
+    </>
+  );
+}

package/src/components/agentMarkdown.test.tsx

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { Fragment, type ReactNode } from 'react';
+import { renderAgentMarkdown } from './agentMarkdown';
+
+/** Render the block array to static HTML so we can assert on structure/text. */
+function html(source: string): string {
+  return renderToStaticMarkup(<Fragment>{renderAgentMarkdown(source) as ReactNode}</Fragment>);
+}
+
+describe('renderAgentMarkdown', () => {
+  it('renders bold and inline code together inline', () => {
+    const out = html('This is **bold** and `code` here.');
+    expect(out).toContain('<strong');
+    expect(out).toContain('>bold</strong>');
+    expect(out).toContain('<code');
+    expect(out).toContain('>code</code>');
+    // Single paragraph containing both.
+    expect((out.match(/<p/g) ?? []).length).toBe(1);
+  });
+
+  it('renders italic', () => {
+    const out = html('an *emphasised* word');
+    expect(out).toContain('<em');
+    expect(out).toContain('>emphasised</em>');
+  });
+
+  it('renders a fenced code block as a <pre> preserving content literally', () => {
+    const out = html('before\n\n```\nconst x = **not bold**;\nline2\n```\n\nafter');
+    expect(out).toContain('<pre');
+    // Markers inside the fence stay literal — no <strong> emitted for them.
+    expect(out).toContain('const x = **not bold**;');
+    expect(out).toContain('line2');
+    // Prose around it still becomes paragraphs.
+    expect(out).toContain('>before</p>');
+    expect(out).toContain('>after</p>');
+  });
+
+  it('renders headings as slightly-bolder paragraphs, not giant tags', () => {
+    const out = html('# Title\n## Sub\n### Small');
+    expect(out).not.toContain('<h1');
+    expect(out).not.toContain('<h2');
+    expect(out).toContain('font-semibold');
+    expect(out).toContain('>Title</p>');
+    expect(out).toContain('>Sub</p>');
+    expect(out).toContain('>Small</p>');
+  });
+
+  it('renders unordered lists (flat)', () => {
+    const out = html('- one\n- two\n- three');
+    expect((out.match(/<ul/g) ?? []).length).toBe(1);
+    expect((out.match(/<li/g) ?? []).length).toBe(3);
+    expect(out).toContain('>one</li>');
+  });
+
+  it('renders ordered lists', () => {
+    const out = html('1. first\n2. second');
+    expect(out).toContain('<ol');
+    expect((out.match(/<li/g) ?? []).length).toBe(2);
+    expect(out).toContain('>first</li>');
+  });
+
+  it('splits paragraphs on blank lines', () => {
+    const out = html('para one\n\npara two');
+    expect((out.match(/<p/g) ?? []).length).toBe(2);
+  });
+
+  it('passes plain text through unchanged', () => {
+    const out = html('just some plain prose with no markup');
+    expect(out).toContain('just some plain prose with no markup');
+    expect(out).not.toContain('<strong');
+    expect(out).not.toContain('<em');
+    expect(out).not.toContain('<code');
+  });
+
+  it('leaves malformed markdown as literal text', () => {
+    // Unclosed bold and a single unpaired star have no valid closing marker, so
+    // they fall back to literal text rather than emitting <strong>/<em>.
+    const out = html('an **unclosed bold marker\n\n5 * 3 = 15');
+    expect(out).not.toContain('<strong');
+    expect(out).not.toContain('<em');
+    expect(out).toContain('**unclosed bold marker');
+    expect(out).toContain('5 * 3 = 15');
+  });
+
+  it('does not treat backtick content as bold', () => {
+    const out = html('`**literal**`');
+    expect(out).toContain('>**literal**</code>');
+    expect(out).not.toContain('<strong');
+  });
+});