npm - brainstorm-companion - Versions diffs - 2.0.1 → 2.0.3 - Mend

brainstorm-companion 2.0.1 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -68,10 +68,9 @@ brainstorm-companion stop
 ```
 **Key behaviors:**
-- `start` with no args works immediately (stores in `/tmp/brainstorm-companion/`)
+- `start` with no args works immediately — auto-isolates by working directory
 - `start` reuses an existing session — never opens duplicate browsers
 - `push` auto-reloads the browser every time — no restart or refresh needed
-- Add `--project-dir .` for project-local storage
 ### Quick Start (MCP / Agent) — 3 calls, zero config
@@ -90,7 +89,7 @@ brainstorm-companion stop
 5. brainstorm_stop_session({})
 ```
-**No arguments required.** `brainstorm_start_session()` works with zero config. Pass `project_dir` for project-local storage or when multiple agents run simultaneously. Sessions persist until `brainstorm_stop_session()` — use `idle_timeout_minutes` for auto-cleanup.
+**No arguments required.** Sessions auto-isolate by working directory — different projects never collide. Sessions persist until `brainstorm_stop_session()` — use `idle_timeout_minutes` for auto-cleanup.
 ---
@@ -231,7 +230,7 @@ graph TD
 | Tool | Description |
 |------|-------------|
-| `brainstorm_start_session` | Start server (or reuse existing). Returns URL. Always pass `project_dir`. |
+| `brainstorm_start_session` | Start server (or reuse existing). No args needed. Returns URL. |
 | `brainstorm_push_screen` | Push HTML content. Browser auto-reloads. Use `slot` + `label` for comparison. |
 | `brainstorm_read_events` | Read user interaction events. Option to clear after reading. |
 | `brainstorm_clear_screen` | Clear a specific slot or all content. |
@@ -244,7 +243,7 @@ graph TD
 ### Single Decision
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...options with data-choice..." })
 3. → Tell user to make their selection in the browser
 4. brainstorm_read_events({})
@@ -255,7 +254,7 @@ graph TD
 ### A/B/C Comparison
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Option A" })
 3. brainstorm_push_screen({ html: "...", slot: "b", label: "Option B" })
 4. → Tell user to compare and pick a preference
@@ -267,7 +266,7 @@ graph TD
 ### Multi-Round Brainstorming
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 // Round 1: Layout
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Grid" })
@@ -290,7 +289,7 @@ graph TD
 ### Progressive Refinement
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 // Show initial mockup
 2. brainstorm_push_screen({ html: "...v1 mockup..." })
@@ -383,26 +382,25 @@ Shows Session ID, URL, uptime, event count, and active slots.
 ## Best Practices
-1. **Always pass `project_dir`** to `brainstorm_start_session` — avoids cross-agent conflicts
-2. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
-3. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
-4. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
-5. **Start with a heading** — `<h2>` describes what the user is looking at
-6. **Add a `.subtitle`** — describes the decision being made
-7. **One decision per screen** — don't combine unrelated choices
-8. **Use slot labels** — `label` makes comparison tabs readable
-9. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
-10. **Tell the user to interact** — after pushing content, let them know the browser is ready
-11. **Read events after user has time** — don't immediately read; wait for user to respond
-12. **Clean up with `brainstorm_stop_session`** — frees the port and removes temp files
+1. **Zero config** — `brainstorm_start_session()` and `brainstorm-companion start` work with no arguments; sessions auto-isolate by working directory
+3. **Never restart to update content** — just call `push_screen` / `push` again; the browser auto-reloads
+4. **One start per workflow** — `start` reuses the existing session automatically
+5. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+6. **Start with a heading** — `<h2>` describes what the user is looking at
+7. **Add a `.subtitle`** — describes the decision being made
+8. **One decision per screen** — don't combine unrelated choices
+9. **Use slot labels** — `label` makes comparison tabs readable
+10. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+11. **Tell the user to interact** — after pushing content, let them know the browser is ready
+12. **Read events after user has time** — don't immediately read; wait for user to respond
+13. **Use `--timeout <min>` for auto-cleanup** — or call `stop` / `brainstorm_stop_session` when done
 ## Common Mistakes
 - **Starting a new session for each update** — DON'T. Call `push_screen` to update the existing browser.
-- **Omitting `project_dir`** — leads to `/tmp` collisions between agents.
 - **Pushing full HTML documents** — push fragments; the frame template adds theming and structure.
 - **Reading events immediately after push** — give the user time to interact first.
-- **Forgetting to stop** — always call `brainstorm_stop_session` when done.
+- **Forgetting to stop** — always call `brainstorm_stop_session` / `stop` when done, or use `--timeout`.
 ## Author

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "brainstorm-companion",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "AI-assisted visual brainstorming companion",
   "type": "commonjs",
   "license": "MIT",

package/skill/SKILL.md CHANGED Viewed

@@ -53,7 +53,7 @@ brainstorm_start_session({
 })
 ```
-**`project_dir` is optional.** Without it, sessions go to `/tmp/brainstorm-companion/`. Pass the current working directory for project-local storage or when multiple agents may run simultaneously.
+**No arguments required.** Sessions are auto-isolated by working directory — different projects never collide, even without `project_dir`. Pass `project_dir` only if you want session files stored inside the project folder.
 **Calling it multiple times is safe** — returns the existing session. Just call `brainstorm_push_screen` to update content.
@@ -344,7 +344,7 @@ All events include a `timestamp` field (Unix ms).
 ### Single Decision
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...options with data-choice..." })
 3. → Tell user to make their selection in the browser
 4. brainstorm_read_events({})
@@ -355,7 +355,7 @@ All events include a `timestamp` field (Unix ms).
 ### A/B/C Comparison
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Option A" })
 3. brainstorm_push_screen({ html: "...", slot: "b", label: "Option B" })
 4. → Tell user to compare and pick a preference
@@ -367,7 +367,7 @@ All events include a `timestamp` field (Unix ms).
 ### Multi-Round Brainstorming
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 // Round 1: Layout
 2. brainstorm_push_screen({ html: "...", slot: "a", label: "Grid" })
@@ -390,7 +390,7 @@ All events include a `timestamp` field (Unix ms).
 ### Progressive Refinement
 ```
-1. brainstorm_start_session({ project_dir: "..." })
+1. brainstorm_start_session()
 // Show initial mockup
 2. brainstorm_push_screen({ html: "...v1 mockup..." })
@@ -407,23 +407,22 @@ All events include a `timestamp` field (Unix ms).
 ## Best Practices
-1. **Always pass `project_dir`** to `brainstorm_start_session` — avoids cross-agent conflicts
-2. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
-3. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
-4. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
-5. **Start with a heading** — `<h2>` describes what the user is looking at
-6. **Add a `.subtitle`** — describes the decision being made
-7. **One decision per screen** — don't combine unrelated choices
-8. **Use slot labels** — `label` makes comparison tabs readable
-9. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
-10. **Tell the user to interact** — after pushing content, let them know the browser is ready
-11. **Read events after user has time** — don't immediately read; wait for user to respond
-12. **Clean up with `brainstorm_stop_session`** — frees the port and removes temp files
+1. **Zero config** — `brainstorm_start_session()` works with no arguments; isolation is automatic
+3. **Never restart to update content** — just call `brainstorm_push_screen` again; the browser auto-reloads
+4. **One `brainstorm_start_session` per workflow** — it reuses the existing session automatically
+5. **Push fragments, not full documents** — the frame template handles `<html>`, theming, and scroll
+6. **Start with a heading** — `<h2>` describes what the user is looking at
+7. **Add a `.subtitle`** — describes the decision being made
+8. **One decision per screen** — don't combine unrelated choices
+9. **Use slot labels** — `label` makes comparison tabs readable
+10. **Use `data-choice` for interaction** — the built-in `toggleSelect` emits events automatically
+11. **Tell the user to interact** — after pushing content, let them know the browser is ready
+12. **Read events after user has time** — don't immediately read; wait for user to respond
+13. **Clean up with `brainstorm_stop_session`** — or use `idle_timeout_minutes` for auto-cleanup
 ## Common Mistakes
 - **Starting a new session for each update** — DON'T. Call `push_screen` to update the existing browser.
-- **Omitting `project_dir`** — leads to `/tmp` collisions between agents.
 - **Pushing full HTML documents** — push fragments; the frame template adds theming and structure.
 - **Reading events immediately after push** — give the user time to interact first.
-- **Forgetting to stop** — always call `brainstorm_stop_session` when done.
+- **Forgetting to stop** — always call `brainstorm_stop_session` when done, or use `idle_timeout_minutes`.

package/skill/visual-companion.md CHANGED Viewed

@@ -152,9 +152,9 @@ brainstorm_read_events()
 When running multi-round comparisons, clear events between rounds to avoid stale data:
 ```
-brainstorm_read_events()           // read current events
-brainstorm_clear_screen({ target: "events" })  // clear event queue
-brainstorm_push_screen({ html: "Round 2..." }) // push next round
+brainstorm_read_events({ clear_after_read: true })  // read and clear in one call
+brainstorm_clear_screen({})                          // clear content for next round
+brainstorm_push_screen({ html: "Round 2..." })       // push next round
 ```
 ### Interpreting Events
@@ -250,10 +250,10 @@ stateDiagram-v2
 This example shows a full workflow for choosing a navigation pattern for a new app.
-### Step 1: Present the question
+### Step 1: Start session and present the question
 ```
-brainstorm_start_session()
+brainstorm_start_session()  // no args needed — opens browser automatically
 brainstorm_push_screen({
   html: `

package/src/cli.js CHANGED Viewed

@@ -185,6 +185,18 @@ function printHelp(command) {
 // Helpers
 // ---------------------------------------------------------------------------
+function printNextSteps() {
+  console.log(`
+Next steps:
+  brainstorm-companion push --html '<h2>Your content</h2>'   Push content to browser
+  brainstorm-companion push file.html --slot a --label "A"   Comparison mode
+  brainstorm-companion events                                 Read user interactions
+  brainstorm-companion stop                                   Stop when done
+Full docs: https://www.npmjs.com/package/brainstorm-companion
+Run: brainstorm-companion push --help    for all CSS classes and options`);
+}
 function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -272,6 +284,7 @@ async function start(argv) {
     const url = existing.serverInfo.url;
     console.log(`Server already running: ${url}`);
     console.log(`Session ID: ${existing.sessionId}`);
+    printNextSteps();
     if (!noOpen) {
       openBrowser(url);
     }
@@ -294,6 +307,7 @@ async function start(argv) {
     instance.server.once('listening', () => {
       console.log(`Server started: ${instance.url}`);
       console.log(`Session ID: ${path.basename(sessionDir)}`);
+      printNextSteps();
       if (!noOpen) {
         openBrowser(instance.url);
       }
@@ -338,6 +352,7 @@ async function start(argv) {
     console.log(`Server started: ${serverInfo.url}`);
     console.log(`Session ID: ${path.basename(sessionDir)}`);
+    printNextSteps();
     if (!noOpen) {
       openBrowser(serverInfo.url);

package/src/mcp.js CHANGED Viewed

@@ -1,10 +1,15 @@
 'use strict';
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const { exec } = require('node:child_process');
 const { startServer } = require('./server');
+function cwdHash() {
+  return crypto.createHash('md5').update(process.cwd()).digest('hex').slice(0, 8);
+}
 class McpServer {
   constructor() {
     this.sessionDir = null;     // absolute path once session is started
@@ -170,7 +175,7 @@ RULES:
         inputSchema: {
           type: 'object',
           properties: {
-            project_dir: { type: 'string', description: 'Project directory for session storage. Optional — defaults to /tmp/brainstorm-companion/. Pass cwd for project-local storage.' },
+            project_dir: { type: 'string', description: 'Optional. Stores session files under <dir>/.superpowers/brainstorm/. If omitted, auto-isolates by working directory.' },
             port: { type: 'number', description: 'Port to bind to (default: random ephemeral)' },
             open_browser: { type: 'boolean', description: 'Open browser automatically (default: true)' },
             idle_timeout_minutes: { type: 'number', description: 'Auto-stop after N minutes idle (default: 0 = no timeout)' }
@@ -247,7 +252,7 @@ Give the user time to interact before reading — don't read immediately after p
     // Determine base directory and create session dir
     const baseDir = project_dir
       ? path.join(project_dir, '.superpowers', 'brainstorm')
-      : '/tmp/brainstorm-companion';
+      : path.join('/tmp', 'brainstorm-companion', cwdHash());
     const sessionId = `${process.pid}-${Date.now()}`;
     const sessionDir = path.join(baseDir, sessionId);
     fs.mkdirSync(sessionDir, { recursive: true });

package/src/session.js CHANGED Viewed

@@ -1,13 +1,18 @@
 'use strict';
+const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
+function cwdHash() {
+  return crypto.createHash('md5').update(process.cwd()).digest('hex').slice(0, 8);
+}
 class SessionManager {
   constructor(projectDir, targetSessionId) {
     this.baseDir = projectDir
-      ? `${projectDir}/.superpowers/brainstorm/`
-      : `/tmp/brainstorm-companion/`;
+      ? path.join(projectDir, '.superpowers', 'brainstorm')
+      : path.join('/tmp', 'brainstorm-companion', cwdHash());
     this.targetSessionId = targetSessionId || null;
   }