Make playground always scaffold new files (#40)

Author: obj-p

README.md

@@ -42,18 +42,16 @@ previewsmcp run MyView.swift --platform ios-simulator
 # Capture a screenshot
 previewsmcp snapshot MyView.swift -o preview.png
 
-# Open a playground — creates a temp file with a starter view and live-reloads on edit
+# Scaffold a new playground file and start a live preview
 previewsmcp playground
+previewsmcp playground MyView.swift    # creates MyView.swift with starter code
 previewsmcp playground --platform ios-simulator
 
-# Or use an existing file
-previewsmcp playground MyView.swift
-
 # Pipe to your editor
 vim $(previewsmcp playground)
 ```
 
-The `playground` command opens a live preview with hot-reload — no project setup needed. Pass an existing file or omit to create a temp one.
+The `playground` command scaffolds a new SwiftUI file with a starter view and opens a live preview with hot-reload. Pass a path to create the file there, or omit for a temp file. Use `run` to preview existing files.
 
 ## MCP Server
 

Sources/PreviewsCLI/BuildHelpers.swift

@@ -48,17 +48,24 @@ let defaultPlaygroundCode = """
     }
     """
 
-/// Create a temporary playground Swift file, returning its URL.
-func createPlaygroundFile(code: String? = nil) throws -> URL {
-    let playgroundDir = FileManager.default.temporaryDirectory
-        .appendingPathComponent("previewsmcp-playground", isDirectory: true)
-    try FileManager.default.createDirectory(at: playgroundDir, withIntermediateDirectories: true)
-
-    let shortID = UUID().uuidString.prefix(8)
-    let fileName = "Playground_\(shortID).swift"
-    let fileURL = playgroundDir.appendingPathComponent(fileName)
-    try (code ?? defaultPlaygroundCode).write(to: fileURL, atomically: true, encoding: .utf8)
+/// Create a playground Swift file, returning its URL.
+/// When `at` is provided, writes to that path (creating parent directories).
+/// Otherwise creates a temp file with a unique name.
+func createPlaygroundFile(code: String? = nil, at outputPath: URL? = nil) throws -> URL {
+    let fileURL: URL
+    if let outputPath {
+        let dir = outputPath.deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        fileURL = outputPath
+    } else {
+        let playgroundDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("previewsmcp-playground", isDirectory: true)
+        try FileManager.default.createDirectory(at: playgroundDir, withIntermediateDirectories: true)
+        let shortID = UUID().uuidString.prefix(8)
+        fileURL = playgroundDir.appendingPathComponent("Playground_\(shortID).swift")
+    }
 
+    try (code ?? defaultPlaygroundCode).write(to: fileURL, atomically: true, encoding: .utf8)
     return fileURL
 }
 

Sources/PreviewsCLI/MCPServer.swift

@@ -220,7 +220,7 @@ func configureMCPServer() async throws -> (Server, Compiler) {
             Tool(
                 name: "preview_playground",
                 description:
-                    "Create a temporary SwiftUI file and start a live preview. Returns session ID and file path for editing. No project setup needed.",
+                    "Create a temporary SwiftUI file and start a live preview for quick experimentation. Returns session ID and file path. For previewing existing files, use preview_start instead.",
                 inputSchema: .object([
                     "type": .string("object"),
                     "properties": .object([

Sources/PreviewsCLI/PlaygroundCommand.swift

@@ -5,10 +5,10 @@ import Foundation
 struct PlaygroundCommand: ParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "playground",
-        abstract: "Create a temporary SwiftUI file and start a live preview"
+        abstract: "Scaffold a new SwiftUI file and start a live preview"
     )
 
-    @Argument(help: "Path to an existing Swift file (creates a temp file if omitted)")
+    @Argument(help: "Output path for the new file (creates a temp file if omitted)")
     var file: String?
 
     @Option(name: .long, help: "Window width")
@@ -26,15 +26,26 @@ struct PlaygroundCommand: ParsableCommand {
     mutating func run() throws {
         let fileURL: URL
         if let file {
-            fileURL = URL(fileURLWithPath: file).standardizedFileURL
-            guard FileManager.default.fileExists(atPath: fileURL.path) else {
-                throw ValidationError("File not found: \(file)")
+            let url = URL(fileURLWithPath: file).standardizedFileURL
+            var isDir: ObjCBool = false
+            if FileManager.default.fileExists(atPath: url.path, isDirectory: &isDir) {
+                if isDir.boolValue {
+                    let example = url.appendingPathComponent("MyView.swift").path
+                    throw ValidationError(
+                        "'\(file)' is a directory. Provide a file path, e.g. '\(example)'")
+                }
+                throw ValidationError(
+                    "File already exists: \(file). Use 'previewsmcp run \(file)' to preview it.")
             }
+            fileURL = try createPlaygroundFile(at: url)
         } else {
             fileURL = try createPlaygroundFile()
         }
 
-        print(fileURL.path)
+        // Use fputs to stdout — print() is fully buffered when piped, which
+        // breaks `vim $(previewsmcp playground)` since the path never flushes.
+        fputs("\(fileURL.path)\n", stdout)
+        fflush(stdout)
         fputs("Edit this file to see live changes.\n", stderr)
 
         let windowWidth = width