feedbackbasket-cli 0.9.0 → 0.9.3

package/README.md

@@ -41,6 +41,8 @@ feedbackbasket feedback update <id> --status PLANNED --agent
 feedbackbasket widget script myproject --agent
 ```
 
+When installing or configuring a widget for the current app, agents should not rely on the CLI default project. First run `feedbackbasket projects list --agent`, match the current app by its real website URL or clearly matching project name, and only create a new project after confirming no existing project belongs to this app. If the only known URL is `localhost`, ask for the production, staging, preview, or intended public URL before creating the project.
+
 ### Install Claude Code Skill
 
 ```bash
@@ -70,11 +72,14 @@ All project commands accept **name or ID** (e.g. `feedbackbasket` or `cmn3c7sgv.
 feedbackbasket projects list                              # List all projects with stats
 feedbackbasket projects show <name-or-id>                 # Project details
 feedbackbasket projects create "My App" --url https://... # Create project
+feedbackbasket projects create "Local Test" --url http://localhost:3000 --allow-local-url
 feedbackbasket projects update myapp --name "New Name"    # Update project
 feedbackbasket projects update myapp --reply-to vlad@example.com  # Set default reply-to email
 feedbackbasket projects delete myapp                      # Delete (with confirmation)
 ```
 
+Use the production, staging, preview, or intended public website URL for projects. The CLI blocks accidental `localhost`/loopback URLs in agent and non-interactive mode unless you pass `--allow-local-url` for an explicitly local-only test project.
+
 ### Feedback
 
 ```bash
@@ -128,21 +133,33 @@ feedbackbasket widget settings myapp --color "#22c55e" --label "Send Feedback"
 feedbackbasket widget settings myapp --position bottom-left --display modal
 feedbackbasket widget settings myapp --email-required --intro "How can we improve?"
 feedbackbasket widget settings myapp --button-radius 10 --button-size regular
-feedbackbasket widget settings myapp --show-email --allow-attachments --guided
+feedbackbasket widget settings myapp --show-email --allow-attachments
 feedbackbasket widget settings myapp --email-read-only --hide-email-when-prefilled
 
 # Configure guided feedback types and follow-up questions
 feedbackbasket widget flow myapp
-feedbackbasket widget flow myapp --enable
-feedbackbasket widget flow myapp --reset-default --enable
+feedbackbasket widget flow myapp --enable                  # guided only when requested
+feedbackbasket widget flow myapp --reset-default --enable  # guided only when requested
 feedbackbasket widget flow myapp --config ./feedback-flow.json
 
 # Get embed code (ready to paste into your HTML)
 feedbackbasket widget script myapp
 ```
 
+For inline trigger mode, load the widget once and call the public API from your own button:
+
+```html
+<button onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })">
+  Feedback
+</button>
+```
+
+Passing the trigger element lets popup mode open beside your custom button. Calling `window.FeedbackWidget.openFeedbackForm()` with no arguments still uses the configured widget position.
+
 Use `--email-read-only` and `--hide-email-when-prefilled` with runtime `userEmail` values from your app. These settings do not store visitor emails in FeedbackBasket widget settings.
 
+The default widget experience is a basic modal. Only switch to popup mode or enable guided feedback when you intentionally want that flow.
+
 `widget flow --config` accepts either a `feedbackFlow` object or a JSON object with a `feedbackFlow` key. V1 supports guided mode with `text`, `textarea`, and `single_choice` follow-up questions.
 
 ```json

package/dist/src/commands/projects.js

@@ -59,9 +59,11 @@ export function createProjectsCommand(getWriter) {
         .description('Create a new project')
         .requiredOption('--url <url>', 'Project URL')
         .option('--description <text>', 'Project description')
+        .option('--allow-local-url', 'Allow localhost URLs for local-only test projects')
         .action(async (name, opts) => {
         const writer = getWriter();
         const client = requireClient();
+        await ensureProjectUrlIsIntentional(opts.url, writer, Boolean(opts.allowLocalUrl));
         const result = await client.createProject({
             name,
             url: opts.url,
@@ -89,6 +91,7 @@ export function createProjectsCommand(getWriter) {
         .option('--url <url>', 'New project URL')
         .option('--description <text>', 'New project description')
         .option('--reply-to <email>', 'Default reply-to email for feedback replies (empty string to clear)')
+        .option('--allow-local-url', 'Allow localhost URLs for local-only test projects')
         .action(async (idOrName, opts) => {
         const writer = getWriter();
         if (!opts.name &&
@@ -100,6 +103,9 @@ export function createProjectsCommand(getWriter) {
         const client = requireClient();
         const resolved = await resolveProject(client, idOrName);
         const id = resolved.id;
+        if (opts.url) {
+            await ensureProjectUrlIsIntentional(opts.url, writer, Boolean(opts.allowLocalUrl));
+        }
         const data = {};
         if (opts.name)
             data['name'] = opts.name;
@@ -225,3 +231,32 @@ function renderProjectDetail(project) {
     }
     console.log();
 }
+async function ensureProjectUrlIsIntentional(url, writer, allowLocalUrl) {
+    if (!isLocalProjectUrl(url) || allowLocalUrl)
+        return;
+    const message = 'Project URL looks like a local development address. Use the production, staging, preview, or intended public website URL, or pass --allow-local-url for a local-only test project.';
+    if (writer.isMachineOutput() || !process.stdin.isTTY) {
+        throw errUsage(message, 'Example: feedbackbasket projects create "My App" --url https://myapp.com');
+    }
+    console.log(`  ${brand.warning('Warning:')} ${message}`);
+    console.log();
+    const confirmed = await confirm('  Use this as a local-only test project URL?', false);
+    if (!confirmed) {
+        throw errUsage('Project URL change cancelled. Re-run with the real website URL.', 'Example: feedbackbasket projects create "My App" --url https://myapp.com');
+    }
+}
+function isLocalProjectUrl(input) {
+    try {
+        const url = new URL(input);
+        const hostname = url.hostname.toLowerCase();
+        return (hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '0.0.0.0' ||
+            hostname === '::1' ||
+            hostname === '[::1]' ||
+            hostname.endsWith('.localhost'));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/commands/widget.js

@@ -153,7 +153,7 @@ export function createWidgetCommand(getWriter) {
                 breadcrumbs: [
                     { action: 'Get embed code', cmd: `feedbackbasket widget script ${projectId}` },
                     { action: 'View settings', cmd: `feedbackbasket widget settings ${projectId}` },
-                    { action: 'Configure guided questions', cmd: `feedbackbasket widget flow ${projectId} --enable` },
+                    { action: 'Configure guided questions', cmd: `feedbackbasket widget flow ${projectId}` },
                 ],
             });
         }
@@ -167,7 +167,7 @@ export function createWidgetCommand(getWriter) {
                 summary: `Widget settings for "${result.projectName}"`,
                 breadcrumbs: [
                     { action: 'Update color', cmd: `feedbackbasket widget settings ${projectId} --color "#22c55e"` },
-                    { action: 'Enable guided flow', cmd: `feedbackbasket widget flow ${projectId} --enable` },
+                    { action: 'View guided flow', cmd: `feedbackbasket widget flow ${projectId}` },
                     { action: 'Get embed code', cmd: `feedbackbasket widget script ${projectId}` },
                 ],
             });
@@ -227,8 +227,8 @@ export function createWidgetCommand(getWriter) {
         writer.ok(result.settings.feedbackFlow ?? DEFAULT_FEEDBACK_FLOW, {
             summary: `Guided feedback flow for "${result.projectName}"`,
             breadcrumbs: [
-                { action: 'Enable guided flow', cmd: `feedbackbasket widget flow ${projectId} --enable` },
-                { action: 'Reset templates', cmd: `feedbackbasket widget flow ${projectId} --reset-default --enable` },
+                { action: 'Enable guided flow if requested', cmd: `feedbackbasket widget flow ${projectId} --enable` },
+                { action: 'Reset templates if requested', cmd: `feedbackbasket widget flow ${projectId} --reset-default --enable` },
                 { action: 'Apply JSON config', cmd: `feedbackbasket widget flow ${projectId} --config ./feedback-flow.json` },
             ],
         });
@@ -243,6 +243,7 @@ export function createWidgetCommand(getWriter) {
         const projectId = await resolveProjectId(client, projectArg);
         const result = await client.getWidgetScript(projectId);
         if (!writer.isMachineOutput()) {
+            const settingsResult = await client.getWidgetSettings(projectId);
             console.log(brand.bold(`Widget embed code for ${result.projectName}`));
             console.log(divider(50));
             console.log();
@@ -252,6 +253,7 @@ export function createWidgetCommand(getWriter) {
             console.log();
             console.log(brand.muted(`  Script URL: ${result.scriptUrl}`));
             console.log();
+            renderInlineTriggerHelp(settingsResult.settings);
         }
         writer.ok(result, {
             summary: `Embed code for "${result.projectName}"`,
@@ -341,6 +343,27 @@ function isRecord(value) {
 function stringValue(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
+function renderInlineTriggerHelp(settings) {
+    if (settings.triggerMode !== 'inline')
+        return;
+    console.log(brand.bold('Custom inline trigger'));
+    console.log(divider(50));
+    console.log();
+    console.log(brand.muted('  Call this from your own button:'));
+    console.log();
+    console.log(`  ${brand.primary('<button onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })">')}`);
+    console.log(`  ${brand.primary('  Feedback')}`);
+    console.log(`  ${brand.primary('</button>')}`);
+    console.log();
+    if (settings.displayMode === 'popup') {
+        console.log(brand.muted('  Passing the trigger keeps popup mode anchored beside your custom button.'));
+    }
+    else {
+        console.log(brand.muted('  Modal mode stays centered; passing the trigger is safe for future popup changes.'));
+    }
+    console.log(brand.muted('  Existing calls to window.FeedbackWidget.openFeedbackForm() still work.'));
+    console.log();
+}
 function renderWidgetSettings(projectName, settings) {
     console.log(brand.bold(`Widget settings — ${projectName}`));
     console.log(divider(40));

package/dist/src/help.js

@@ -61,7 +61,7 @@ export function renderRootHelp() {
     lines.push(`${INDENT}${brand.muted('$')} feedbackbasket feedback list --category BUG --status OPEN`);
     lines.push(`${INDENT}${brand.muted('$')} feedbackbasket bugs list --severity high`);
     lines.push(`${INDENT}${brand.muted('$')} feedbackbasket widget script myapp`);
-    lines.push(`${INDENT}${brand.muted('$')} feedbackbasket widget flow myapp --reset-default --enable`);
+    lines.push(`${INDENT}${brand.muted('$')} feedbackbasket widget settings myapp --display modal`);
     lines.push(`${INDENT}${brand.muted('$')} feedbackbasket projects create "My App" --url https://myapp.com`);
     lines.push('');
     // Learn More

package/dist/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.9.0";
-export declare const USER_AGENT = "FeedbackBasket-CLI/0.9.0";
+export declare const VERSION = "0.9.3";
+export declare const USER_AGENT = "FeedbackBasket-CLI/0.9.3";

package/dist/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '0.9.0';
+export const VERSION = '0.9.3';
 export const USER_AGENT = `FeedbackBasket-CLI/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedbackbasket-cli",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "description": "Command-line interface for FeedbackBasket — manage feedback from your terminal",
   "type": "module",
   "main": "dist/src/cli.js",

package/skills/feedbackbasket/SKILL.md

@@ -53,6 +53,16 @@ feedbackbasket projects delete <name-or-id> --yes
 
 All project commands accept **name or ID**. Names are matched case-insensitively with fuzzy suggestions on typos.
 
+**Project selection rule for widget installs:** when the user asks to add a FeedbackBasket widget, bubble, popup, modal, or feedback button to the current app, first resolve the FeedbackBasket project for this app. Do not use the CLI default project just because one is configured.
+
+1. Identify the current app's real website URL or intended public URL from the user, app config, docs, or existing FeedbackBasket embed code.
+2. Run `feedbackbasket projects list --agent` and look for an existing project whose `url` matches that site or whose name clearly matches the current app.
+3. If exactly one project matches, use that project ID/name for `widget settings`, `widget script`, and feedback commands.
+4. If multiple projects could match, ask the user which one to use.
+5. If no project matches, ask whether to create a new project for this app, then create it with the confirmed real URL. Do not create a project from a localhost URL unless the user explicitly wants a local-only test project.
+
+**Project URL rule for agents:** confirm the real website URL before creating or updating a project. Never use `localhost`, `127.0.0.1`, `0.0.0.0`, `::1`, or a local dev server URL unless the user explicitly says the project is only for local testing. If the repo only exposes a local URL, ask for the production, staging, preview, or intended public URL. Do not guess a public domain from package names, git remotes, or environment variables. For an explicitly local-only test project, pass `--allow-local-url`.
+
 ### Feedback
 ```bash
 # Read
@@ -99,19 +109,39 @@ feedbackbasket widget settings <project>
 feedbackbasket widget settings <project> --color "#22c55e" --label "Send Feedback"
 feedbackbasket widget settings <project> --position bottom-left --display modal
 feedbackbasket widget settings <project> --email-required --intro "How can we improve?"
-feedbackbasket widget settings <project> --show-email --allow-attachments --guided
+feedbackbasket widget settings <project> --show-email --allow-attachments
 feedbackbasket widget settings <project> --email-read-only --hide-email-when-prefilled
 
 # Guided feedback types and follow-up questions
 feedbackbasket widget flow <project>
-feedbackbasket widget flow <project> --enable
-feedbackbasket widget flow <project> --reset-default --enable
+feedbackbasket widget flow <project> --enable  # only when the user chooses guided feedback
+feedbackbasket widget flow <project> --reset-default --enable  # only when the user chooses guided feedback
 feedbackbasket widget flow <project> --config ./feedback-flow.json
 ```
 
+For inline trigger mode, load the widget once and call the public API from the host app's custom button:
+
+```html
+<button onclick="window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })">
+  Feedback
+</button>
+```
+
+In React:
+
+```tsx
+<button onClick={(event) => window.FeedbackWidget.openFeedbackForm({ trigger: event.currentTarget })}>
+  Feedback
+</button>
+```
+
+Passing the trigger element lets popup mode open beside the custom button. Calling `window.FeedbackWidget.openFeedbackForm()` with no arguments still uses the configured widget position.
+
 `email-read-only` and `hide-email-when-prefilled` control behavior only when the host app passes a runtime `userEmail` value. Do not store visitor emails in widget settings.
 
-`widget flow --config` accepts either a `feedbackFlow` object or a JSON object with a `feedbackFlow` key. Use it when an agent needs to customize visitor choices such as Bug report, Feature request, and General feedback. Supported v1 question types are `text`, `textarea`, and `single_choice`.
+Use the basic widget experience by default: `displayMode` stays `modal`, and guided feedback stays disabled. Ask the user before switching to `popup` or enabling guided feedback. If the user does not care, keep modal + basic feedback.
+
+`widget flow --config` accepts either a `feedbackFlow` object or a JSON object with a `feedbackFlow` key. Use it only when the user wants to customize visitor choices such as Bug report, Feature request, and General feedback. Supported v1 question types are `text`, `textarea`, and `single_choice`.
 
 ### Team
 ```bash
@@ -128,14 +158,18 @@ feedbackbasket setup claude            # Install this skill for Claude Code
 
 ## Common Agent Workflows
 
-### Set up a new project end-to-end
+### Add a widget to the current app
 ```bash
+# First resolve the project for this app. Do not rely on the CLI default project.
+feedbackbasket projects list --agent
+
+# If no existing project matches the current app's real URL/name, create one after confirming the URL.
 feedbackbasket projects create "My App" --url https://myapp.com --agent
 feedbackbasket widget script "My App" --agent
 # Agent gets the embed code, adds it to the HTML
 feedbackbasket widget settings "My App" --color "#22c55e" --label "Feedback" --agent
-# Optional: enable the guided wizard with Bug, Feature, and General templates
-feedbackbasket widget flow "My App" --reset-default --enable --agent
+# Optional, only when requested: enable the guided wizard with Bug, Feature, and General templates
+# feedbackbasket widget flow "My App" --reset-default --enable --agent
 ```
 
 ### Triage new feedback
@@ -158,6 +192,39 @@ feedbackbasket feedback create "Login button is broken" \
 ```
 Agent mode returns the created feedback ID, dashboard URL, and feedback object. Created feedback is analyzed by AI and follows the project's notification settings.
 
+### File agent-found issues in FeedbackBasket
+
+When the user says "file this in FeedbackBasket", "log this bug", "create feedback for this issue", "add this to FeedbackBasket", or similar, create a concise feedback item for the issue the agent found.
+
+Before creating the item, resolve the target project:
+
+1. If the user explicitly names a FeedbackBasket project, use that project.
+2. If the current repo/app clearly matches exactly one FeedbackBasket project name or project URL from `feedbackbasket projects list --agent`, use that project.
+3. If the CLI default project clearly matches the current repo/app, use it.
+4. If multiple projects are plausible, ask the user which FeedbackBasket project to file it under.
+5. Do not silently guess the project when it is ambiguous.
+
+Keep agent-filed feedback short and dashboard-friendly:
+
+- Title: under 80 characters, action-oriented, no stack traces.
+- Content: 1 to 3 short paragraphs, ideally under 600 characters, focused on the user-visible problem, expected behavior, and actual behavior.
+- Do not paste long logs, full reasoning chains, or broad investigation notes into the body.
+- Put structured context in metadata: `source=agent`, `found_by=<agent>`, `repo=<name>`, `branch=<branch>`, `route=<path>`, `file=<path>`, `severity=<low|medium|high>`, `test=<command>`.
+
+Use:
+
+```bash
+feedbackbasket feedback create "<short title>" \
+  --content "<brief user-visible issue description>" \
+  --project <project-name-or-id> \
+  --type bug \
+  --metadata source=agent \
+  --metadata found_by=codex \
+  --agent
+```
+
+After creation, report the feedback ID and dashboard URL to the user.
+
 ### Investigate high-priority bugs
 ```bash
 feedbackbasket bugs list --severity high --agent