plotlink-ows 1.0.26 → 1.0.30

package/app/lib/generate-claude-md.ts

@@ -0,0 +1,139 @@
+import fs from "fs";
+import path from "path";
+import { CONFIG_DIR } from "./paths";
+
+const CLAUDE_MD_PATH = path.join(CONFIG_DIR, "CLAUDE.md");
+
+/** Read the installed package version from package.json */
+function getVersion(): string {
+  const pkgPath = path.join(__dirname, "..", "..", "package.json");
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
+  } catch {
+    return "unknown";
+  }
+}
+
+function generateContent(version: string, port: number): string {
+  return `# PlotLink OWS — Local Writer API (v${version})
+
+> Auto-generated by PlotLink OWS on startup. Do not edit manually.
+
+Local writer app running at \`http://localhost:${port}\`.
+All endpoints except auth use \`Authorization: Bearer {token}\` headers.
+
+## Authentication
+
+The OWS passphrase is stored in \`~/.plotlink-ows/.env\` as \`OWS_PASSPHRASE\`.
+For login, the passphrase is hashed with HMAC-SHA256 and compared against the stored hash.
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| \`/api/auth/status\` | GET | No | Check if passphrase is configured |
+| \`/api/auth/setup\` | POST | No | First-run passphrase setup (≥4 chars) → returns \`{ token }\` |
+| \`/api/auth/login\` | POST | No | Login with passphrase → returns \`{ token }\` (24h TTL) |
+| \`/api/auth/verify\` | GET | Bearer | Check token validity |
+| \`/api/auth/reset-passphrase\` | POST | Bearer | Update passphrase |
+
+## Publishing
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| \`/api/publish/preflight\` | GET | Check wallet balance, Filebase config |
+| \`/api/publish/file\` | POST | Publish story on-chain (SSE stream of progress events) |
+| \`/api/publish/retry-index\` | POST | Retry indexing for a published file |
+| \`/api/publish/upload-cover\` | POST | Upload cover image — FormData \`file\` field, **WebP or JPEG only**, max 500KB → returns \`{ cid }\` |
+| \`/api/publish/upload-plot-image\` | POST | Upload plot illustration — FormData \`file\` field, **WebP or JPEG only**, max 500KB → returns \`{ cid, url }\` |
+| \`/api/publish/update-storyline\` | POST | Update storyline metadata (coverCid, genre, language, isNsfw) |
+
+**Publish flow:** Upload to IPFS → estimate gas → sign with OWS wallet → broadcast → confirm → index on plotlink.xyz (8s delay + 10 retries × 30s). Genesis files call \`createStoryline\`, plot files (\`plot-*.md\`) call \`chainPlot\`. Content limit: 10K chars.
+
+**Cover update workflow:**
+1. \`POST /api/publish/upload-cover\` with image file → get \`cid\`
+2. \`POST /api/publish/update-storyline\` with \`{ storylineId, coverCid: cid }\` → updates on plotlink.xyz
+
+**Metadata update workflow:**
+1. \`POST /api/publish/update-storyline\` with \`{ storylineId, genre?, language?, isNsfw? }\`
+
+Both upload-cover and update-storyline sign messages with the OWS wallet.
+
+## Stories
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| \`/api/stories\` | GET | List all stories |
+| \`/api/stories/archived\` | GET | List archived stories |
+| \`/api/stories/archive\` | POST | Archive a story \`{ name }\` |
+| \`/api/stories/restore\` | POST | Restore archived story \`{ name }\` |
+| \`/api/stories/:name\` | GET | Story detail with file contents |
+| \`/api/stories/:name/:file\` | GET | Single file content and publish status |
+| \`/api/stories/:name/:file\` | PUT | Update file content \`{ content }\` |
+| \`/api/stories/:name/:file/publish-status\` | POST | Record publish result (txHash, storylineId, etc.) |
+| \`/api/stories/:name/:file/mark-not-indexed\` | POST | Mark file as not indexed \`{ indexError? }\` |
+
+## Terminal
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| \`/api/terminal/spawn\` | POST | Spawn Claude CLI session for a story \`{ storyName?, resume? }\` |
+| \`/api/terminal/session/:storyName\` | GET | Get stored session ID for a story |
+| \`/api/terminal/status\` | GET | List all active terminal sessions |
+| \`/api/terminal/rename\` | POST | Rename session \`{ oldName, newName }\` |
+| \`/api/terminal/stop\` | POST | Kill default PTY (legacy) |
+| \`/api/terminal/:storyName\` | DELETE | Kill a story's PTY |
+| \`/api/terminal/:storyName/discard\` | DELETE | Kill PTY and clean metadata |
+| \`/ws/terminal\` | WebSocket | Live PTY relay \`?token={token}&story={name}&resume={bool}\` |
+
+## Other Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| \`/api/wallet\` | GET | Wallet info and balances (ETH, USDC, PLOT) |
+| \`/api/wallet/create\` | POST | Create OWS wallet if not exists |
+| \`/api/dashboard\` | GET | Writer dashboard stats (stories, costs, royalties) |
+| \`/api/settings/register-agent\` | POST | Register wallet on ERC-8004 |
+| \`/api/settings/generate-binding\` | POST | Generate wallet binding proof |
+| \`/api/settings/link-status\` | GET | Check ERC-8004 registration status |
+| \`/api/health\` | GET | Health check |
+
+## Story File Structure
+
+Stories live in \`~/.plotlink-ows/stories/{story-name}/\`:
+
+\`\`\`
+stories/{story-name}/
+  structure.md    # Outline, characters, arc
+  genesis.md      # Synopsis hook (~1000 chars)
+  plot-01.md      # Chapter 1 (max 10K chars)
+  ...
+\`\`\`
+
+## Supported Genres (21)
+
+Romance, Fantasy, Science Fiction, Mystery, Thriller, Horror, Adventure, Historical Fiction, Contemporary Lit, Humor, Poetry, Non-Fiction, Fanfiction, Short Story, Paranormal, Werewolf, LGBTQ+, New Adult, Teen Fiction, Diverse Lit, Others
+
+## Supported Languages (11)
+
+English, Chinese, Korean, Japanese, Spanish, French, Hindi, Arabic, Portuguese, Russian, Others
+`;
+}
+
+/**
+ * Write/update ~/.plotlink-ows/CLAUDE.md on startup.
+ * Skips the write if the file already contains the current version stamp.
+ */
+export function generateClaudeMd(): void {
+  const version = getVersion();
+  const port = Number(process.env.APP_PORT) || 7777;
+
+  // Check if the file already matches the current version
+  if (fs.existsSync(CLAUDE_MD_PATH)) {
+    try {
+      const firstLine = fs.readFileSync(CLAUDE_MD_PATH, "utf-8").split("\n")[0];
+      if (firstLine.includes(`(v${version})`)) return;
+    } catch { /* regenerate on read error */ }
+  }
+
+  fs.writeFileSync(CLAUDE_MD_PATH, generateContent(version, port), "utf-8");
+  console.log(`  Updated ~/.plotlink-ows/CLAUDE.md (v${version})`);
+}

package/app/lib/publish.ts

@@ -461,6 +461,41 @@ export async function uploadCoverImage(
   return data.cid;
 }
 
+/**
+ * Upload a plot illustration image to PlotLink via signed API call.
+ * Returns the IPFS CID and URL of the uploaded image.
+ */
+export async function uploadPlotImage(
+  walletName: string,
+  walletAddress: `0x${string}`,
+  imageFile: File,
+): Promise<{ cid: string; url: string }> {
+  const PLOTLINK_URL = process.env.NEXT_PUBLIC_APP_URL || "https://plotlink.xyz";
+  const account = createOwsAccount(walletName, walletAddress);
+
+  const timestamp = Date.now();
+  const message = `PlotLink: Upload plot image\nTimestamp: ${timestamp}`;
+  const signature = await account.signMessage({ message });
+
+  const formData = new FormData();
+  formData.append("file", imageFile);
+  formData.append("message", message);
+  formData.append("signature", signature);
+
+  const res = await fetch(`${PLOTLINK_URL}/api/upload-plot-image`, {
+    method: "POST",
+    body: formData,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({})) as Record<string, string>;
+    throw new Error(err.error || `Plot image upload failed: HTTP ${res.status}`);
+  }
+
+  const data = await res.json() as { cid: string; url: string };
+  return data;
+}
+
 /**
  * Update storyline metadata (cover, genre, language, NSFW) on PlotLink via signed API call.
  * Uses createOwsAccount for signing (not raw owsSignMsg).

package/app/routes/publish.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
-import { publishStoryline, publishPlot, getEthBalance, estimatePublishCost, uploadCoverImage, updateStoryline } from "../lib/publish";
+import { publishStoryline, publishPlot, getEthBalance, estimatePublishCost, uploadCoverImage, uploadPlotImage, updateStoryline } from "../lib/publish";
 import { keccak256, toBytes } from "viem";
 import { listAgentWallets, getBaseAddress } from "../../lib/ows/wallet";
 
@@ -217,9 +217,10 @@ publish.post("/upload-cover", async (c) => {
       return c.json({ error: "Image exceeds 500KB limit" }, 400);
     }
 
-    // Validate file type
-    if (!file.type.startsWith("image/")) {
-      return c.json({ error: "File must be an image (WebP or JPEG recommended)" }, 400);
+    // Validate file type — only WebP and JPEG accepted by the plotlink server
+    const allowedTypes = ["image/webp", "image/jpeg"];
+    if (!allowedTypes.includes(file.type)) {
+      return c.json({ error: "Only WebP and JPEG images are accepted" }, 400);
     }
 
     const cid = await uploadCoverImage(wallet.name, address as `0x${string}`, file);
@@ -230,6 +231,41 @@ publish.post("/upload-cover", async (c) => {
   }
 });
 
+/** POST /api/publish/upload-plot-image — upload plot illustration with wallet signature */
+publish.post("/upload-plot-image", async (c) => {
+  try {
+    const wallets = listAgentWallets();
+    const wallet = wallets.find((w) => w.name.startsWith("plotlink-writer"));
+    if (!wallet) return c.json({ error: "No OWS wallet" }, 400);
+
+    const address = getBaseAddress(wallet);
+    if (!address) return c.json({ error: "No EVM address on wallet" }, 400);
+
+    const formData = await c.req.formData();
+    const file = formData.get("file");
+    if (!file || !(file instanceof File)) {
+      return c.json({ error: "No image file provided" }, 400);
+    }
+
+    // Validate file size (500KB max)
+    if (file.size > 500 * 1024) {
+      return c.json({ error: "Image exceeds 500KB limit" }, 400);
+    }
+
+    // Validate file type — only WebP and JPEG accepted by the plotlink server
+    const allowedTypes = ["image/webp", "image/jpeg"];
+    if (!allowedTypes.includes(file.type)) {
+      return c.json({ error: "Only WebP and JPEG images are accepted" }, 400);
+    }
+
+    const result = await uploadPlotImage(wallet.name, address as `0x${string}`, file);
+    return c.json(result);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : "Plot image upload failed";
+    return c.json({ error: message }, 500);
+  }
+});
+
 /** POST /api/publish/update-storyline — update storyline metadata with wallet signature */
 publish.post("/update-storyline", async (c) => {
   try {

package/app/server.ts

@@ -23,6 +23,7 @@ import { terminalRoutes, attachTerminalWs } from "./routes/terminal";
 import { storiesRoutes } from "./routes/stories";
 import { settingsRoutes } from "./routes/settings";
 import { initDb } from "./db";
+import { generateClaudeMd } from "./lib/generate-claude-md";
 import { execSync } from "child_process";
 import fs from "fs";
 
@@ -117,6 +118,9 @@ async function start() {
   // Auto-migrate from old package-relative paths
   migrateOldData();
 
+  // Generate/update ~/.plotlink-ows/CLAUDE.md for agent discovery
+  generateClaudeMd();
+
   // Run Prisma db push to ensure schema is up to date
   const schemaPath = path.join(__dirname, "prisma", "schema.prisma");
   execSync(`npx prisma db push --schema ${schemaPath} --skip-generate`, {

package/app/web/components/PreviewPanel.tsx

@@ -56,6 +56,14 @@ export function PreviewPanel({ storyName, fileName, authFetch, onPublish, publis
   const [editSuccess, setEditSuccess] = useState(false);
   const coverInputRef = useRef<HTMLInputElement>(null);
 
+  // Inline illustration state
+  const [showIllustrations, setShowIllustrations] = useState(false);
+  const [illustrationUploading, setIllustrationUploading] = useState(false);
+  const [illustrationError, setIllustrationError] = useState<string | null>(null);
+  const [uploadedImages, setUploadedImages] = useState<Array<{ cid: string; url: string }>>([]);
+  const [copiedIndex, setCopiedIndex] = useState<number | null>(null);
+  const illustrationInputRef = useRef<HTMLInputElement>(null);
+
   const prevFileRef = useRef<string | null>(null);
 
   const loadFile = useCallback(async () => {
@@ -153,6 +161,45 @@ export function PreviewPanel({ storyName, fileName, authFetch, onPublish, publis
     setEditError(null);
   }, []);
 
+  // Handle illustration image upload from File object
+  const uploadIllustration = useCallback(async (file: File) => {
+    if (file.size > 500 * 1024) {
+      setIllustrationError("Image exceeds 500KB limit");
+      return;
+    }
+    const allowedTypes = ["image/webp", "image/jpeg"];
+    if (!allowedTypes.includes(file.type)) {
+      setIllustrationError("Only WebP and JPEG images are accepted");
+      return;
+    }
+    setIllustrationUploading(true);
+    setIllustrationError(null);
+    try {
+      const formData = new FormData();
+      formData.append("file", file);
+      const res = await authFetch("/api/publish/upload-plot-image", {
+        method: "POST",
+        body: formData,
+      });
+      if (!res.ok) {
+        const err = await res.json();
+        throw new Error(err.error || "Upload failed");
+      }
+      const data = await res.json();
+      setUploadedImages((prev) => [...prev, { cid: data.cid, url: data.url }]);
+    } catch (err) {
+      setIllustrationError(err instanceof Error ? err.message : "Upload failed");
+    } finally {
+      setIllustrationUploading(false);
+      if (illustrationInputRef.current) illustrationInputRef.current.value = "";
+    }
+  }, [authFetch]);
+
+  const handleIllustrationInput = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) uploadIllustration(file);
+  }, [uploadIllustration]);
+
   // Save storyline edits (cover upload + metadata update)
   const handleEditSave = useCallback(async () => {
     if (!fileData?.storylineId) return;
@@ -215,6 +262,9 @@ export function PreviewPanel({ storyName, fileName, authFetch, onPublish, publis
     setEditError(null);
     setEditSuccess(false);
     setEditMetaLoaded(false);
+    setShowIllustrations(false);
+    setUploadedImages([]);
+    setIllustrationError(null);
   }, [storyName, fileName]);
 
   // Fetch current storyline metadata when edit panel opens
@@ -407,6 +457,70 @@ export function PreviewPanel({ storyName, fileName, authFetch, onPublish, publis
               {saving ? "Saving..." : "Save"}
             </button>
           </div>
+          {/* Inline illustration upload for plot files */}
+          {isPlot && (
+            <div className="px-3 py-1.5 border-t border-border">
+              <label className="flex items-center gap-1.5 text-xs text-muted cursor-pointer">
+                <input
+                  type="checkbox"
+                  checked={showIllustrations}
+                  onChange={(e) => setShowIllustrations(e.target.checked)}
+                  className="rounded border-border"
+                />
+                Add illustrations in the plot
+              </label>
+              {showIllustrations && (
+                <div className="mt-2 flex flex-col gap-2">
+                  <div
+                    className="border-2 border-dashed border-border rounded p-3 flex flex-col items-center gap-1.5 cursor-pointer hover:border-accent transition-colors"
+                    onClick={() => illustrationInputRef.current?.click()}
+                    onDragOver={(e) => { e.preventDefault(); e.stopPropagation(); }}
+                    onDrop={(e) => {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      const file = e.dataTransfer.files?.[0];
+                      if (file) uploadIllustration(file);
+                    }}
+                  >
+                    <input
+                      ref={illustrationInputRef}
+                      type="file"
+                      accept="image/webp,image/jpeg"
+                      onChange={handleIllustrationInput}
+                      className="hidden"
+                    />
+                    <span className="text-xs text-muted">
+                      {illustrationUploading ? "Uploading..." : "Drop image here or click to browse"}
+                    </span>
+                    <span className="text-xs text-muted">WebP/JPEG, max 500KB</span>
+                  </div>
+                  {illustrationError && (
+                    <span className="text-error text-xs">{illustrationError}</span>
+                  )}
+                  {uploadedImages.map((img, i) => (
+                    <div key={img.cid} className="border border-border rounded p-2 flex flex-col gap-1 bg-surface">
+                      <span className="text-xs text-green-700">Image uploaded! Copy the markdown below and paste it where you want the illustration to appear in your plot:</span>
+                      <div className="flex items-center gap-1.5">
+                        <code className="flex-1 text-xs bg-background px-2 py-1 rounded font-mono break-all">
+                          ![Scene description]({img.url})
+                        </code>
+                        <button
+                          onClick={() => {
+                            navigator.clipboard.writeText(`![Scene description](${img.url})`);
+                            setCopiedIndex(i);
+                            setTimeout(() => setCopiedIndex(null), 2000);
+                          }}
+                          className="px-2 py-1 text-xs border border-border rounded hover:bg-surface shrink-0"
+                        >
+                          {copiedIndex === i ? "Copied!" : "Copy"}
+                        </button>
+                      </div>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
         </div>
       )}