@vibes.diy/prompts 14.3.175 → 14.3.177

package/llms/backend.md

@@ -335,7 +335,11 @@ const routes = await ctx.github.routes(); // [{ repo, accountLogin, binderHandle
   calls to a service the owner holds a key for (`Authorization: Bearer
   ${ctx.secrets.KEY}` to an admitted API). Never write a value anywhere users
   can read it (a doc, a response body). Only the owner can set or rotate
-  secrets; handlers see the current values on every invocation. **A visitor's
+  secrets; handlers see the current values on every invocation. A feature
+  that cannot work until the owner has set one is a setup item: the `/setup`
+  verdict and the owner-only Setup surface are the use-vibe docs' *Some apps
+  need setup before they work*, and the skill that needs the secret
+  contributes the item and its linked steps. **A visitor's
   own account (their GitHub, Threads, Instagram) is never a secret and never a
   pasted token — it is a connection**: declare it in `config.connections`, let
   the platform hold the credential, and read it through `@vibes.diy/social` or

package/llms/spotify.md

@@ -19,31 +19,38 @@ visitor to a developer console to mint one: that is the flow connections exists
 replace. The console trip below is for the **owner** of this app, once, and for
 nobody else.
 
-## 1. Bring your own app credentials, and explain how
-
-The owner registers an app with Spotify, once:
-
-1. Open the Spotify developer dashboard and log in with a Spotify account.
-2. Create an app — any name and description; a redirect URI is not used by this
-   flow, so put the app's own URL in if the form insists on one.
-3. Open the app's settings and copy the **Client ID**.
-4. Reveal and copy the **Client secret**.
-5. Set both on the vibe as `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` — the
-   vibe's settings page, or `vibes-diy secrets set SPOTIFY_CLIENT_ID <the id>` and
-   `vibes-diy secrets set SPOTIFY_CLIENT_SECRET <the secret>`.
-
-The app carries those five steps in its own UI, because the person reading them is
-the person who has to do them.
-
-When the credentials are missing, the app shows the owner the setup steps for a Spotify app instead of an error.
-
-The backend answers `{ ok: false, reason: "missing-key" }` when either
-`ctx.secrets.SPOTIFY_CLIENT_ID` or `ctx.secrets.SPOTIFY_CLIENT_SECRET` is absent,
-and the client renders the numbered steps, naming the Spotify developer dashboard
-and both secret names in so many words so the owner knows what to create and what
-to call it. Two secrets means two ways to be half-configured: say "missing-key"
-once and list both, rather than letting one set and one unset look like a broken
-API.
+## 1. The setup item: the owner's Spotify app credentials
+
+The owner registers an app with Spotify, once. The Setup surface the item
+lands on — the owner-only entry in the app's navigation, the verdict from
+`/setup`, the re-read on focus that unlocks search in place — is the use-vibe
+docs' *Some apps need setup before they work*; this recipe contributes one
+item to it. The Spotify item is the credential pair: the backend answers missing-key while either ctx.secrets.SPOTIFY_CLIENT_ID or ctx.secrets.SPOTIFY_CLIENT_SECRET is absent, and its steps link the Spotify developer dashboard by URL and name both secrets in so many words.
+The steps are written for someone who has never opened the dashboard, so each
+one is a link to the exact page and uses the words that page uses:
+
+1. Open the Spotify developer dashboard: <https://developer.spotify.com/dashboard>
+   (log in with a Spotify account). Press **Create app** — any name and
+   description; for **Redirect URIs** put the app's own address, since this
+   flow never uses one — and save.
+2. Open the app you made and press **Settings**. Copy the **Client ID**, then
+   press **View client secret** and copy that too.
+3. Open this vibe's **Settings** tab on vibes.diy:
+   `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` (that is
+   **My Vibes** → this vibe → **Settings**). Under **Secrets**, enter
+   `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`, paste each value, and
+   save. From a terminal the same thing is
+   `npx vibes-diy secrets set SPOTIFY_CLIENT_ID --vibe <ownerHandle>/<appSlug>`
+   and the same for `SPOTIFY_CLIENT_SECRET`.
+4. Come back to the app. Search works the moment both are saved; no redeploy.
+
+Those steps are the item's copy on the Setup surface, with the vibe's real
+handle and slug filled in from the `ownerHandle` and `appSlug` the `/setup`
+route hands over. Two secrets means two ways to be half-configured: one item,
+done only when both are present, so one set and one unset reads as *To do*
+rather than as a broken API. In the consumer flow, a search whose pair is not
+set reads *Search is not open yet*; the owner's Setup entry is where the
+steps are, and later it is where a rotated secret goes.
 
 Only the owner can set or rotate a secret, and handlers see the current value on
 every invocation — so the page starts working the moment the pair lands, with no
@@ -141,9 +148,10 @@ API, and `{ "error", "error_description" }` on the token endpoint. Classify and
 pass the reason through:
 
 - `invalid_client` from the token endpoint — the id and secret do not match a real
-  app. Show the setup steps from section 1 again.
+  app. Say so, and point the owner at the Setup entry: the item reads *Done*
+  because both values are present, and one of them is wrong.
 - `401` from the Web API — mint a fresh token and retry once; if the second try is
-  also 401, show the setup steps.
+  also 401, say so and point the owner at the Setup entry the same way.
 - `429` — Spotify is rate-limiting the owner's app. The `Retry-After` header is
   seconds; say "Spotify asked us to wait N seconds" rather than "no results".
 - `404` — no such artist, album or track. Keep the id on screen.
@@ -247,6 +255,16 @@ export async function fetch(request, ctx) {
 
   // An uncaught throw reaches the app as a bare 500 naming only the error class, so every route answers with a reason.
   try {
+    // The setup verdict: ready for everyone, the item (and the handle + slug the Setup screen
+    // links with) for the owner alone.
+    if (url.pathname === "/setup") {
+      const owner = ctx.userInfo?.userHandle === ctx.appInfo.ownerHandle;
+      const items = [{ id: "spotify-app", label: "Spotify app credentials", done: credentials(ctx) !== null }];
+      const ready = items.every((item) => item.done);
+      if (!owner) return json({ ok: true, ready, owner });
+      return json({ ok: true, ready, owner, items, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+    }
+
     if (url.pathname === "/search") {
       const q = (url.searchParams.get("q") ?? "").trim();
       if (q === "") return json({ ok: true, tracks: [], artists: [] });
@@ -305,21 +323,71 @@ function artistRow(a) {
 
 ### `App.jsx`
 ```jsx app=spotify-browser
-import React, { useState } from "react";
-import { Button, Field, Input, Row } from "@vibes.diy/pouf";
+import React, { useEffect, useRef, useState } from "react";
+import { apiFetch } from "use-vibes";
+import { Badge, Button, Field, Heading, Input, Row, Stack, Text } from "@vibes.diy/pouf";
+
+// The setup verdict, read on mount and again whenever the app comes back into view: the owner
+// sets the pair in another tab and returns, and search unlocks without a reload.
+function useSetup() {
+  const [setup, setSetup] = useState(null); // { ready, owner, items?, ownerHandle?, appSlug? }
+  const latest = useRef(0);
+  useEffect(() => {
+    // Mount, focus and visibility reads overlap; only the latest one may land, or a slow stale
+    // answer overwrites a fresh one.
+    const load = () => {
+      const n = ++latest.current;
+      apiFetch("/setup").then((r) => r.json()).catch(() => ({ ready: false, owner: false })).then((s) => { if (n === latest.current) setSetup(s); });
+    };
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
+  }, []);
+  return setup;
+}
+
+// The item's steps: each one a link to the exact page, in that page's own words, with this
+// vibe's real handle and slug filled in.
+function setupSteps(vibe) {
+  return [
+    { href: "https://developer.spotify.com/dashboard", link: "Spotify developer dashboard", text: ": log in, press Create app (any name; put this app's own address under Redirect URIs), and save." },
+    { href: "https://developer.spotify.com/dashboard", link: "your app's Settings", text: ": copy the Client ID, then press View client secret and copy that too." },
+    { href: `https://vibes.diy/vibes/mine/${vibe}/settings`, link: "this vibe's Settings tab", text: `: under Secrets, enter SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, paste each value, and save — or run npx vibes-diy secrets set SPOTIFY_CLIENT_ID --vibe ${vibe} and the same for SPOTIFY_CLIENT_SECRET.` },
+  ];
+}
 
-const SETUP_STEPS = [
-  "Open the Spotify developer dashboard and log in.",
-  "Create an app — any name and description will do.",
-  "Copy the Client ID from the app's settings.",
-  "Reveal and copy the Client secret.",
-  "Set them on this vibe as SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET.",
-];
+// The Setup surface, the owner's alone.
+function SetupScreen({ setup }) {
+  const item = setup.items.find((i) => i.id === "spotify-app");
+  return (
+    <Stack>
+      <Heading>Setup</Heading>
+      <Row gap={2}>
+        <Text>{item.label}</Text>
+        <Badge tone={item.done ? "up" : "info"}>{item.done ? "Done" : "To do"}</Badge>
+      </Row>
+      <ol>
+        {setupSteps(`${setup.ownerHandle}/${setup.appSlug}`).map((step) => (
+          <li key={step.link}>
+            Open <a href={step.href} target="_blank" rel="noreferrer">{step.link}</a>
+            {step.text}
+          </li>
+        ))}
+      </ol>
+      <Text muted>Both values stay on the server and are never sent to the browser. Search works the moment they are saved.</Text>
+    </Stack>
+  );
+}
 
 export default function App() {
+  const setup = useSetup();
+  const [screen, setScreen] = useState("search");
   const [query, setQuery] = useState("");
   const [tracks, setTracks] = useState([]);
   const [problem, setProblem] = useState(null);
+  const ready = setup?.ready === true;
 
   const search = async () => {
     const res = await fetch(`/_api/search?q=${encodeURIComponent(query)}`);
@@ -333,46 +401,55 @@ export default function App() {
   };
 
   return (
-    <div>
-      <Row gap={2} align="top">
-        <Field label="Search">{(id, describedBy) => <Input id={id} describedBy={describedBy} value={query} onChange={setQuery} placeholder="Search Spotify" />}</Field>
-        <Button type="button" onClick={search}>Search</Button>
+    <Stack>
+      <Row gap={2}>
+        <Button variant="quiet" onClick={() => setScreen("search")}>Search</Button>
+        {/* The Setup entry: the owner's alone, highlighted while the item is still to do, quiet once done. */}
+        {setup?.owner && (
+          <Button variant={ready ? "quiet" : "solid"} onClick={() => setScreen("setup")}>
+            Setup{ready ? "" : " · to do"}
+          </Button>
+        )}
       </Row>
 
-      {problem?.reason === "missing-key" && (
-        <section>
-          <h2>Add your Spotify app credentials</h2>
-          <ol>
-            {SETUP_STEPS.map((step) => (
-              <li key={step}>{step}</li>
+      {screen === "setup" && setup?.owner ? (
+        <SetupScreen setup={setup} />
+      ) : (
+        <Stack>
+          {ready ? (
+            <Row gap={2} align="top">
+              <Field label="Search">{(id, describedBy) => <Input id={id} describedBy={describedBy} value={query} onChange={setQuery} placeholder="Search Spotify" />}</Field>
+              <Button type="button" onClick={search}>Search</Button>
+            </Row>
+          ) : (
+            <Text muted>Search is not open yet.</Text>
+          )}
+
+          {problem?.reason === "rate-limited" && <Text>Spotify asked us to wait {problem.retryAfter} seconds.</Text>}
+          {problem && problem.reason !== "rate-limited" && <Text role="alert">{problem.message}</Text>}
+
+          <ul>
+            {tracks.map((t) => (
+              <li key={t.id}>
+                {t.image && <img src={t.image} alt="" width={64} height={64} />}
+                <a href={t.url} target="_blank" rel="noreferrer">
+                  {t.name}
+                </a>{" "}
+                — {t.artists}
+              </li>
             ))}
-          </ol>
-          <p>Both values stay on the server and are never sent to the browser.</p>
-        </section>
+          </ul>
+
+          <section>
+            <h3>What this page can see</h3>
+            <p>
+              Spotify's public catalog — search, artists, albums and tracks. Your own top tracks, playlists and saved songs
+              belong to your Spotify account and are not part of this.
+            </p>
+          </section>
+        </Stack>
       )}
-      {problem?.reason === "rate-limited" && <p>Spotify asked us to wait {problem.retryAfter} seconds.</p>}
-      {problem && !["missing-key", "rate-limited"].includes(problem.reason) && <p role="alert">{problem.message}</p>}
-
-      <ul>
-        {tracks.map((t) => (
-          <li key={t.id}>
-            {t.image && <img src={t.image} alt="" width={64} height={64} />}
-            <a href={t.url} target="_blank" rel="noreferrer">
-              {t.name}
-            </a>{" "}
-            — {t.artists}
-          </li>
-        ))}
-      </ul>
-
-      <section>
-        <h3>What this page can see</h3>
-        <p>
-          Spotify's public catalog — search, artists, albums and tracks. Your own top tracks, playlists and saved songs
-          belong to your Spotify account and are not part of this.
-        </p>
-      </section>
-    </div>
+    </Stack>
   );
 }
 ```