p-dev-harness 0.3.0 → 0.4.0

package/workspace-snapshot/files/apps/gui/components/custom/first-run-stepper.tsx

@@ -0,0 +1,199 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+  CheckCircle2,
+  ChevronDown,
+  ChevronRight,
+  Circle,
+  Lock,
+  XCircle,
+} from "lucide-react";
+import type {
+  FirstRunReadiness,
+  FirstRunStep,
+  FirstRunStepStatus,
+} from "@harness/setup/first-run-readiness";
+
+import { SPACING } from "@/lib/constants";
+import { cn } from "@/lib/utils";
+import { StatusBadge } from "@/components/custom/status-badge";
+import { Button } from "@/components/ui/button";
+
+function statusVariant(
+  status: FirstRunStepStatus,
+  setupNeeded = false,
+): "success" | "warning" | "destructive" | "secondary" {
+  switch (status) {
+    case "complete":
+      return "success";
+    case "blocked":
+      return setupNeeded ? "secondary" : "destructive";
+    case "ready":
+    case "in_progress":
+      return setupNeeded ? "secondary" : "warning";
+    default:
+      return "secondary";
+  }
+}
+
+function statusLabel(
+  status: FirstRunStepStatus,
+  setupNeeded = false,
+): string {
+  switch (status) {
+    case "not_started":
+      return "Not started";
+    case "in_progress":
+      return setupNeeded ? "Setup needed" : "In progress";
+    case "blocked":
+      return setupNeeded ? "Setup needed" : "Blocked";
+    case "ready":
+      return "Ready";
+    case "complete":
+      return "Complete";
+  }
+}
+
+function StepIcon({
+  step,
+  setupNeeded,
+}: {
+  step: FirstRunStep;
+  setupNeeded: boolean;
+}) {
+  if (step.status === "complete") {
+    return <CheckCircle2 className="size-4 shrink-0 text-emerald-600" />;
+  }
+  if (step.status === "blocked" && !setupNeeded) {
+    return <XCircle className="size-4 shrink-0 text-destructive" />;
+  }
+  if (step.status === "not_started") {
+    return <Lock className="size-4 shrink-0 text-muted-foreground" />;
+  }
+  return <Circle className="size-4 shrink-0 text-muted-foreground" />;
+}
+
+interface FirstRunStepperProps {
+  readiness: FirstRunReadiness;
+  renderStepContent: (stepId: FirstRunStep["id"]) => React.ReactNode;
+  onSwitchToAdvanced?: () => void;
+}
+
+export function FirstRunStepper({
+  readiness,
+  renderStepContent,
+  onSwitchToAdvanced,
+}: FirstRunStepperProps) {
+  const [expandedStepId, setExpandedStepId] = useState(
+    readiness.currentStepId,
+  );
+
+  useEffect(() => {
+    setExpandedStepId(readiness.currentStepId);
+  }, [readiness.currentStepId]);
+
+  return (
+    <div className={SPACING.section}>
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div className={SPACING.stackSm}>
+          <h3 className="text-lg font-semibold">First-run readiness flow</h3>
+          <p className="text-sm text-muted-foreground">
+            Complete each step in order. Later steps stay inspectable until
+            prerequisites are ready.
+          </p>
+        </div>
+        {onSwitchToAdvanced ? (
+          <Button type="button" variant="outline" onClick={onSwitchToAdvanced}>
+            Show all setup sections
+          </Button>
+        ) : null}
+      </div>
+
+      <ol className={SPACING.list}>
+        {readiness.steps.map((step) => {
+          const isCurrent = step.id === readiness.currentStepId;
+          const expanded = expandedStepId === step.id;
+          const canExpand = step.inspectable;
+          const setupNeeded =
+            step.blockers.length > 0 &&
+            step.blockers.every((blocker) => blocker.tone === "setup_needed");
+
+          return (
+            <li
+              key={step.id}
+              className={cn(
+                "rounded-lg border border-border",
+                isCurrent && "border-primary/40 shadow-sm",
+              )}
+            >
+              <button
+                type="button"
+                className="flex w-full cursor-pointer items-start gap-3 p-4 text-left disabled:cursor-not-allowed"
+                onClick={() => {
+                  if (canExpand) {
+                    setExpandedStepId(expanded ? readiness.currentStepId : step.id);
+                  }
+                }}
+                disabled={!canExpand}
+              >
+                <StepIcon step={step} setupNeeded={setupNeeded} />
+                <div className="min-w-0 flex-1 space-y-2">
+                  <div className="flex flex-wrap items-center gap-2">
+                    <p className="text-sm font-medium">{step.label}</p>
+                    <StatusBadge
+                      label={statusLabel(step.status, setupNeeded)}
+                      variant={statusVariant(step.status, setupNeeded)}
+                    />
+                    {isCurrent ? (
+                      <StatusBadge label="Current" variant="secondary" />
+                    ) : null}
+                  </div>
+                  <p className="text-sm text-muted-foreground">{step.summary}</p>
+                  {step.primaryAction && step.actionable ? (
+                    <p className="text-sm font-medium text-foreground">
+                      Primary action: {step.primaryAction.label}
+                    </p>
+                  ) : null}
+                  {step.blockers[0] && isCurrent && !setupNeeded ? (
+                    <p className="text-sm text-destructive">
+                      {step.blockers[0].action}
+                    </p>
+                  ) : step.blockers[0] && isCurrent ? (
+                    <p className="text-sm text-muted-foreground">
+                      {step.blockers[0].action}
+                    </p>
+                  ) : null}
+                </div>
+                {canExpand ? (
+                  expanded ? (
+                    <ChevronDown className="size-4 shrink-0 text-muted-foreground" />
+                  ) : (
+                    <ChevronRight className="size-4 shrink-0 text-muted-foreground" />
+                  )
+                ) : null}
+              </button>
+
+              {expanded ? (
+                <div
+                  className={cn(
+                    "border-t border-border p-4",
+                    !step.actionable && step.status === "not_started"
+                      ? "pointer-events-none opacity-60"
+                      : undefined,
+                  )}
+                >
+                  {renderStepContent(step.id)}
+                </div>
+              ) : null}
+            </li>
+          );
+        })}
+      </ol>
+
+      <p className="text-sm text-muted-foreground">
+        {readiness.prohibitedActionsNote}
+      </p>
+    </div>
+  );
+}

package/workspace-snapshot/files/apps/gui/components/custom/github-token-help-disclosure.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import Image from "next/image";
+import { FORM } from "@/lib/constants";
+import {
+  GITHUB_CLASSIC_PAT_SCOPES,
+  GITHUB_PAT_SETTINGS_URL,
+  GITHUB_TOKEN_HELP_DISCLOSURE_LABEL,
+} from "@harness/setup/github-workflow-permissions";
+
+const SCREENSHOTS = {
+  generateNewToken: "/setup/github-token/github-pat-generate-new-token.png",
+  generateClassic: "/setup/github-token/github-pat-generate-classic.png",
+  verifyEmail: "/setup/github-token/github-pat-verify-email.png",
+} as const;
+
+function HelpScreenshot({
+  src,
+  alt,
+}: {
+  src: string;
+  alt: string;
+}) {
+  return (
+    <div className="overflow-hidden rounded-md border border-border bg-muted/20">
+      <Image
+        src={src}
+        alt={alt}
+        width={640}
+        height={360}
+        className="h-auto w-full max-w-sm"
+        sizes="(max-width: 640px) 100vw, 320px"
+      />
+    </div>
+  );
+}
+
+export function GitHubTokenHelpDisclosure() {
+  return (
+    <details className="rounded-md border border-border/80 bg-muted/10 p-3">
+      <summary className="cursor-pointer text-sm text-muted-foreground hover:text-foreground">
+        {GITHUB_TOKEN_HELP_DISCLOSURE_LABEL}
+      </summary>
+      <ol className="mt-3 list-decimal space-y-4 pl-5 text-sm text-muted-foreground">
+        <li className="space-y-1">
+          <p>
+            Go to{" "}
+            <a
+              href={GITHUB_PAT_SETTINGS_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-foreground underline underline-offset-2"
+            >
+              {GITHUB_PAT_SETTINGS_URL}
+            </a>
+            .
+          </p>
+          <p className={FORM.secretHint}>
+            Open <strong className="font-medium text-foreground">Personal access tokens</strong>{" "}
+            and choose the <strong className="font-medium text-foreground">Tokens (classic)</strong>{" "}
+            tab if GitHub shows both classic and fine-grained options.
+          </p>
+        </li>
+        <li className="space-y-2">
+          <p>Click <strong className="font-medium text-foreground">Generate new token</strong>.</p>
+          <HelpScreenshot
+            src={SCREENSHOTS.generateNewToken}
+            alt="GitHub Personal access tokens page with Generate new token button"
+          />
+        </li>
+        <li className="space-y-2">
+          <p>
+            Choose{" "}
+            <strong className="font-medium text-foreground">
+              Generate new token (classic)
+            </strong>
+            .
+          </p>
+          <p className={FORM.secretHint}>
+            Use classic for the guided happy path. Fine-grained tokens can work,
+            but they require repo-specific permissions and are better for advanced
+            setup.
+          </p>
+          <HelpScreenshot
+            src={SCREENSHOTS.generateClassic}
+            alt="GitHub dropdown showing Generate new token classic for general use"
+          />
+        </li>
+        <li className="space-y-2">
+          <p>
+            If GitHub asks you to verify your email, complete that step before
+            continuing.
+          </p>
+          <HelpScreenshot
+            src={SCREENSHOTS.verifyEmail}
+            alt="GitHub email verification prompt with Verify via email button"
+          />
+        </li>
+        <li>
+          Give the token a clear name, for example{" "}
+          <strong className="font-medium text-foreground">
+            Product Development Harness
+          </strong>
+          .
+        </li>
+        <li className="space-y-1">
+          <p>Select these scopes:</p>
+          <ul className="list-disc space-y-1 pl-5">
+            {GITHUB_CLASSIC_PAT_SCOPES.map((scope) => (
+              <li key={scope.id}>
+                <strong className="font-medium text-foreground">{scope.id}</strong>
+                {" — "}
+                {scope.description}
+              </li>
+            ))}
+          </ul>
+        </li>
+        <li>
+          Click <strong className="font-medium text-foreground">Generate token</strong>{" "}
+          at the bottom of the page.
+        </li>
+        <li className="space-y-1">
+          <p>
+            Copy the token immediately and store it somewhere safe. GitHub only
+            shows it once.
+          </p>
+          <p className={FORM.secretHint}>
+            Paste the copied token into the field above, then click Verify.
+          </p>
+        </li>
+      </ol>
+      <div className="mt-4 rounded-md border border-dashed border-border/80 bg-background/50 p-3 text-xs text-muted-foreground">
+        <p className="font-medium text-foreground">Advanced option</p>
+        <p className="mt-1">
+          Fine-grained tokens can also work if they have access to each target
+          repo and include Contents write plus Workflows write permissions. Use
+          this only if you want repo-specific access control.
+        </p>
+      </div>
+    </details>
+  );
+}