@vibes.diy/prompts 14.3.174 → 14.3.176

package/README.md

@@ -21,7 +21,7 @@ From the group chat to the front counter. A character bot that answers in your v
 
 ## Yours to control
 
-Private by default — or open to the world. You choose. Keep an app to the people you invite, or publish it so anyone can use and remix it. You set who can read, write, and open it.
+Private by default — or open to the world. You choose. Keep an app to the people you invite, or make it Public so anyone can use and remix it. You set who can read, write, and open it.
 
 > Your app's data lives in a centralized cloud database. "Private" means access-gated from other people — not encrypted, and not hidden from the platform.
 

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>
   );
 }
 ```