added pormpt

.changeset/mod-quest-tutorial-prompt.md

@@ -0,0 +1,5 @@
+---
+"playground-cli": patch
+---
+
+`playground mod` now nudges users toward the guided tutorial: when a quest track is started from the picker, the post-clone "Next steps" hint reads `edit with claude (prompt: "start tutorial")` instead of the plain `edit with claude`. The quest and app pickers also tear down their Ink instance fully before the next screen mounts, so a half-unmounted picker can no longer swallow the following screen's keystrokes or leave a stale frame on top of it.

src/commands/mod/QuestPicker.tsx

@@ -28,8 +28,13 @@ interface Props {
     repoRef: GitHubRepoRef;
     /** Branch to read `quests.json` from (defaults to `main`). */
     branch?: string;
-    /** Resolves once the user starts the tutorial (or the picker auto-skips). */
-    onDone: () => void;
+    /**
+     * Resolves once the user is done with the picker. `startedTutorial` is true
+     * only when the user explicitly pressed "Start tutorial" on a real quest
+     * track; it is false when the picker auto-skips (no `quests.json` / empty
+     * manifest / parse error), so the caller can tailor the post-clone hint.
+     */
+    onDone: (startedTutorial: boolean) => void;
     /** User cancelled the whole flow. */
     onCancel: () => void;
 }
@@ -57,13 +62,13 @@ export function QuestPicker({ repoRef, branch, onDone, onCancel }: Props) {
             // like the absent one; rendering a quest-less picker would dead-end
             // the whole `mod` (no start row, only `q` to quit).
             if (!m || m.quests.length === 0) {
-                onDone();
+                onDone(false);
                 return;
             }
             setManifest(m);
         } catch {
             // Malformed manifest or transient error — same fall-through.
-            onDone();
+            onDone(false);
         } finally {
             setFetching(false);
         }
@@ -91,7 +96,7 @@ export function QuestPicker({ repoRef, branch, onDone, onCancel }: Props) {
             return;
         }
         if (fetching || !manifest) return;
-        if (key.return && quests.length > 0) onDone();
+        if (key.return && quests.length > 0) onDone(true);
     });
 
     if (fetching) {

src/commands/mod/index.ts

@@ -27,6 +27,7 @@ import { defaultRepoName } from "../../utils/git/repoName.js";
 import { runCliCommand } from "../../cli-runtime.js";
 import { parseGitHubRepoUrl, type GitHubRepoRef } from "../../utils/mod/source.js";
 import { fetchBulletinJson, getBulletinGateway } from "../../utils/bulletinGateway.js";
+import { editWithClaudeStep } from "./nextSteps.js";
 
 interface FetchedAppMetadata {
     name?: string;
@@ -126,17 +127,19 @@ async function runModCommand(rawDomain: string | undefined): Promise<void> {
                 }
             }
         }
+        let startedTutorial = false;
         if (repoRef) {
             // Capture into a const so the value type-narrows inside the closure
             // (a `let` would widen back to `GitHubRepoRef | null`).
             const ref = repoRef;
-            const continued = await withSpan("cli.mod.quest-picker", "browse quests", () =>
+            const result = await withSpan("cli.mod.quest-picker", "browse quests", () =>
                 pickQuest(ref, questBranch),
             );
-            if (!continued) {
+            if (!result.continued) {
                 process.exitCode = 0;
                 return;
             }
+            startedTutorial = result.startedTutorial;
         }
 
         const targetDir = await withSpan("cli.mod.resolve-target", "resolve target directory", () =>
@@ -171,7 +174,7 @@ async function runModCommand(rawDomain: string | undefined): Promise<void> {
         if (ok && !setupRan) {
             console.log("  Next steps:");
             console.log(`  1. cd ${targetDir}`);
-            console.log("  2. edit with claude");
+            console.log(editWithClaudeStep(startedTutorial));
             console.log("  3. playground deploy --playground");
         }
         if (!ok) process.exitCode = 1;
@@ -202,41 +205,67 @@ async function fetchAppMetadata(registry: any, domain: string): Promise<FetchedA
     return await fetchBulletinJson<FetchedAppMetadata>(cid, getBulletinGateway());
 }
 
-function pickQuest(repoRef: GitHubRepoRef, branch?: string): Promise<boolean> {
+interface QuestPickResult {
+    /** False only when the user quit the picker (abort the whole mod). */
+    continued: boolean;
+    /** True only when the user pressed "Start tutorial" on a real quest track. */
+    startedTutorial: boolean;
+}
+
+function pickQuest(repoRef: GitHubRepoRef, branch?: string): Promise<QuestPickResult> {
     return new Promise((resolve) => {
+        let result: QuestPickResult = { continued: false, startedTutorial: false };
         const app = render(
             React.createElement(QuestPicker, {
                 repoRef,
                 branch,
-                onDone: () => {
+                onDone: (startedTutorial: boolean) => {
+                    result = { continued: true, startedTutorial };
+                    // Erase the frame and fully tear the picker down BEFORE the
+                    // next screen mounts — see browseAndPick for why a clean exit
+                    // matters when two Ink instances would otherwise overlap.
+                    app.clear();
                     app.unmount();
-                    resolve(true);
                 },
                 onCancel: () => {
+                    result = { continued: false, startedTutorial: false };
+                    app.clear();
                     app.unmount();
-                    resolve(false);
                 },
             }),
         );
+        // Resolve only once Ink has fully exited, so the previous screen's
+        // raw-mode stdin handlers are gone before the caller mounts the next.
+        void app.waitUntilExit().then(() => resolve(result));
     });
 }
 
 function browseAndPick(registry: any): Promise<AppEntry | null> {
     return new Promise((resolve) => {
+        let picked: AppEntry | null = null;
         const app = render(
             React.createElement(AppBrowser, {
                 registry,
                 moddableOnly: true,
                 onSelect: (selected: AppEntry) => {
+                    picked = selected;
+                    // Erase the picker's frame and fully tear it down before the
+                    // next screen mounts. Two live Ink instances share raw-mode
+                    // stdin: a half-unmounted AppBrowser (left in its `checking`
+                    // state, whose useInput swallows Enter) would otherwise eat
+                    // the next picker's keystrokes, and its retained frame would
+                    // render on top of the new one.
+                    app.clear();
                     app.unmount();
-                    resolve(selected);
                 },
                 onCancel: () => {
+                    picked = null;
+                    app.clear();
                     app.unmount();
-                    resolve(null);
                 },
             }),
         );
+        void app.waitUntilExit().then(() => resolve(picked));
     });
 }
 

src/commands/mod/nextSteps.test.ts

@@ -0,0 +1,27 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, it } from "vitest";
+import { editWithClaudeStep } from "./nextSteps.js";
+
+describe("editWithClaudeStep", () => {
+    it("nudges toward the tutorial prompt when a quest track was started", () => {
+        expect(editWithClaudeStep(true)).toBe('  2. edit with claude (prompt: "start tutorial")');
+    });
+
+    it("stays generic for a plain mod (no tutorial started)", () => {
+        expect(editWithClaudeStep(false)).toBe("  2. edit with claude");
+    });
+});

src/commands/mod/nextSteps.ts

@@ -0,0 +1,26 @@
+// Copyright (C) Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * The "edit with claude" line of the post-clone "Next steps" block. For a quest
+ * track the user actually started, it nudges them toward the prepopulated AI
+ * prompt that kicks off the guided tutorial; a plain mod has no such entry
+ * point, so it stays generic.
+ */
+export function editWithClaudeStep(startedTutorial: boolean): string {
+    return startedTutorial
+        ? '  2. edit with claude (prompt: "start tutorial")'
+        : "  2. edit with claude";
+}