wtt-connect 0.2.43 → 0.2.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtt-connect",
-  "version": "0.2.43",
+  "version": "0.2.45",
   "private": false,
   "description": "WTT-native connector daemon for Codex, Claude Code, Cursor, Gemini, ACP, and other coding agent surfaces.",
   "type": "module",

package/src/main.js

@@ -97,6 +97,9 @@ function parseArgs(args) {
     else if (a === '--preview-name') out.previewName = args[++i];
     else if (a === '--preview-token') out.previewToken = args[++i];
     else if (a === '--keep-last') out.keepLast = Number(args[++i]);
+    else if (a === '--snapshot-dir') out.snapshotDir = args[++i];
+    else if (a === '--snapshot-entry') out.snapshotEntry = args[++i];
+    else if (a === '--no-snapshot') out.noSnapshot = true;
     else if (a === '--timeout') out.timeout = Number(args[++i]) * 1000;
     else if (a === '--sender-agent-id') out.senderAgentId = args[++i];
     else if (a === '--sender-token') out.senderToken = args[++i];
@@ -134,8 +137,8 @@ Commands:
   upload-artifact --dir <path>  Upload an OpenDesign/artifact directory to WTT
   opendesign-upload --dir <path>
                                   Alias for upload-artifact
-  preview-port --port <port> [--topic-id <id>]
-                                  Create a Cloud Sandbox port preview URL through sandbox outbox
+  preview-port --port <port> [--topic-id <id>] [--snapshot-dir <dir>]
+                                  Create a Cloud Sandbox preview URL and optional persistent snapshot
   cleanup-previews                Stop preview servers previously registered by this agent
   help                           Show this help
 `);
@@ -146,9 +149,10 @@ async function previewPort(config, argv) {
   if (!Number.isInteger(port) || port < 1024 || port > 65535 || port === 3000) {
     throw new Error('preview-port requires --port <1024-65535>, excluding 3000');
   }
+  const keepLast = previewKeepLast(config, argv);
   const cleanup = cleanupOldPreviews(config, {
     currentPort: port,
-    keepLast: previewKeepLast(config, argv),
+    keepLast: Math.max(0, keepLast - 1),
   });
   const preview = await createSandboxPreviewFromOutbox(config, port, {
     name: String(argv.previewName || argv.title || '').trim(),
@@ -158,7 +162,17 @@ async function previewPort(config, argv) {
   const url = preview.preview_url || preview.url;
   if (!url) throw new Error('Cloud Sandbox preview API returned no URL');
   const title = String(argv.title || argv.previewName || preview.name || 'Cloud Sandbox Preview').trim();
-  const markdown = preview.markdown || `[preview_url:${title}](${url})`;
+  const snapshot = argv.noSnapshot ? null : await createPreviewSnapshot(config, argv, { title });
+  const snapshotUrl = snapshot?.snapshot_url || '';
+  const markdown = JSON.stringify({
+    type: 'cloud_sandbox_preview',
+    title,
+    preview_url: url,
+    url,
+    ...(snapshotUrl ? { snapshot_url: snapshotUrl } : {}),
+    ...(snapshot?.artifact_url ? { artifact_url: snapshot.artifact_url } : {}),
+    ...(snapshot?.artifact_id ? { artifact_id: snapshot.artifact_id } : {}),
+  });
   const topicId = String(argv.topicId || argv.sourceId || '').trim();
   let published = null;
   if (topicId) {
@@ -169,6 +183,8 @@ async function previewPort(config, argv) {
         type: 'cloud_sandbox_preview',
         port,
         preview_url: url,
+        ...(snapshotUrl ? { snapshot_url: snapshotUrl } : {}),
+        ...(snapshot?.artifact_id ? { artifact_id: snapshot.artifact_id } : {}),
         preview_cleanup: cleanup,
       });
     } finally {
@@ -176,7 +192,60 @@ async function previewPort(config, argv) {
     }
   }
   recordPreview(config, { port, url, name: preview.name || title });
-  console.log(JSON.stringify({ ok: true, port, url, preview_url: url, markdown, cleanup, published }, null, 2));
+  console.log(JSON.stringify({ ok: true, port, url, preview_url: url, snapshot, markdown, cleanup, published }, null, 2));
+}
+
+async function createPreviewSnapshot(config, argv, { title = 'Cloud Sandbox Preview' } = {}) {
+  const dir = String(argv.snapshotDir || '').trim();
+  if (!dir) return null;
+  const resolved = resolveSnapshotDir(dir, config);
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(`snapshot directory not found: ${resolved}`);
+  }
+  const store = new DurableStore(config.storeFile).load();
+  const artifacts = new ArtifactManager(config, store);
+  const entry = String(argv.snapshotEntry || 'index.html').trim();
+  const artifact = await artifacts.uploadDirectory(resolved, {
+    source: 'cloud_sandbox_preview',
+    sourceId: String(argv.topicId || argv.sourceId || ''),
+    title,
+    entry,
+    type: 'cloud_sandbox_preview_snapshot',
+    metadata: {
+      uploaded_by: 'wtt-connect',
+      command: 'preview-port',
+      live_preview_port: Number(argv.port || argv._?.[0] || 0),
+    },
+  });
+  const previewUrl = absoluteWttUrl(config.wttBaseUrl, artifact.preview_url || artifact.url || '');
+  return {
+    artifact_id: artifact.artifact_id || artifact.id || '',
+    artifact_url: absoluteWttUrl(config.wttBaseUrl, artifact.url || ''),
+    snapshot_url: previewUrl,
+    entry,
+    dir: resolved,
+  };
+}
+
+function resolveSnapshotDir(dir, config) {
+  const expanded = dir.startsWith('~/') ? path.join(process.env.HOME || '', dir.slice(2)) : dir;
+  const base = path.resolve(config.workDir || process.cwd());
+  const resolved = path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+  const roots = [
+    config.workDir,
+    config.artifactDir,
+    config.persistentOutputDir,
+  ].filter(Boolean).map((root) => path.resolve(root));
+  if (!roots.some((root) => isPathInside(resolved, root))) {
+    throw new Error(`snapshot-dir refused path outside WTT workspace/state/persistent roots: ${resolved}`);
+  }
+  return resolved;
+}
+
+function absoluteWttUrl(base, maybeRelative) {
+  if (!maybeRelative) return '';
+  if (/^https?:\/\//i.test(maybeRelative)) return maybeRelative;
+  return `${String(base || '').replace(/\/$/, '')}${String(maybeRelative).startsWith('/') ? '' : '/'}${maybeRelative}`;
 }
 
 async function cleanupPreviewsCommand(config, argv) {

package/src/runner.js

@@ -943,11 +943,11 @@ function renderCloudSandboxStorageInstruction(config, topicId = '') {
     '- Before publishing a preview URL, verify the server is actually listening and serving content with `curl -fsS http://127.0.0.1:<port>/ >/dev/null`.',
     '- If local curl fails, fix or restart the web server first. Never publish a preview URL for a dead port.',
     '- `wtt-connect preview-port` automatically keeps the most recent preview servers for this agent and stops older registered previews beyond the retention limit. Default retention is 3 live previews; use `--keep-last <n>` only when the user asks.',
-    '- For historical results that should remain available after preview cleanup, also save static HTML, screenshots, reports, or build artifacts under the persistent R2 output directory and publish them as files/artifacts. Live preview URLs are for recent interactive previews, not permanent archival storage.',
+    '- For static pages, animations, charts, dashboards, and HTML demos, pass the generated static directory to `wtt-connect preview-port --snapshot-dir <dir> --snapshot-entry index.html` so WTT stores a persistent snapshot fallback. Live preview URLs are for recent interactive previews; snapshots/artifacts preserve history after cleanup.',
     '- If you start a web server in the sandbox and the user should preview it, call the Cloudflare Sandbox outbound Worker directly with curl and include the returned `preview_url` in your reply as `[preview_url:Short Title](<preview_url>)`.',
     '- Preview ports must be 1024-65535 and cannot be 3000. For Vite/Next-style dev servers prefer 5173, 4173, or 8080.',
     `- Preview curl rule: curl -sS -X POST "\${WTT_SANDBOX_OUTBOX_URL:-http://wtt.preview}/preview-port" -H 'content-type: application/json' -d '{"agent_id":"'\${WTT_AGENT_ID:-cloud-agent}'","port":<port>}'`,
-    `- Prefer automatic WTT publishing when topic id is available: wtt-connect preview-port --port <port>${topicId ? ` --topic-id ${topicId}` : ' --topic-id <topic_id>'} --title "Short Title". This publishes a cloud_sandbox_preview card and is a convenience wrapper around the same sandbox outbound Worker.`,
+    `- Prefer automatic WTT publishing when topic id is available: wtt-connect preview-port --port <port>${topicId ? ` --topic-id ${topicId}` : ' --topic-id <topic_id>'} --title "Short Title" --snapshot-dir <static_dir> --snapshot-entry index.html. This publishes a cloud_sandbox_preview card with live and snapshot URLs.`,
   );
   return lines.join('\n');
 }