@superdesign/cli 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,263 @@
+SuperDesign helps you (1) find design inspirations/styles and (2) generate/iterate design drafts on an infinite canvas.
+
+---
+
+# Core scenarios (what this skill handles)
+
+1. **Help me design X** (feature/page/flow)
+2. **Set design system**
+3. **Help me improve design of X**
+
+# Quickstart
+
+Install CLI
+
+```
+npm install -g @superdesign/cli@latest
+```
+
+Install skills for any coding agent
+
+```
+npx skills add superdesigndev/superdesign-skill
+```
+
+Prompt in any agent
+
+```
+/superdesign help me design X
+```
+
+--
+
+## Tooling overview
+
+### A) Inspiration & Style Tools (generic, always available)
+
+Use these to discover style direction, references, and brand context:
+
+- **Search prompt library** (style/components/pages)
+
+  ```bash
+  superdesign search-prompts --keyword "<keyword>" --json
+  superdesign search-prompts --tags "style" --json
+  superdesign search-prompts --tags "style" --keyword "<style keyword>" --json
+  ```
+
+- **Get full prompt details**
+
+  ```bash
+  superdesign get-prompts --slugs "<slug1,slug2,...>" --json
+  ```
+
+- **Extract brand guide from a URL**
+  ```bash
+  superdesign extract-brand-guide --url https://example.com --json
+  ```
+
+### B) Canvas Design Tools
+
+Use design agent to generate high quality design drafts:
+
+- Create project (supports prompt / prompt file / HTML)
+- Create design draft
+- Iterate design draft (replace / branch)
+- Plan flow pages → execute flow pages
+- Fetch specific design draft
+
+---
+
+## Overall SOP for designing features on top of existing app:
+
+1. Investigate existing UI, workflow
+2. Setup design system file if not exist yet
+3. Requirements gathering: use askQuestion tool to clarify requirements with users (Optionally use Inspiration tool to find inspiration when needed)
+4. Ask user whether ready to design in superdesign OR implement UI directly
+5. If yes to superdesign
+   5.1 Create/update a pixel perfect html replica of current UI of page that we will design on top of in `.superdesign/replica_html_template/<name>.html` (html should only contain & reflect how UI look now, the actual design should be handled by superdesign agent)
+   5.2 Create project with this replica html + design system guide
+   5.3 Start desigining by iterating & branching design draft based on designDraft ID returned from project
+
+## Always-on rules
+
+- Design system should live at: `.superdesign/design-system.md`
+- If `.superdesign/design-system.md` is missing, run **Design System Setup** first.
+- Use `askQuestion` to ask high-signal questions (constraints, taste, tradeoffs).
+- Always use `--json` for machine parsing.
+
+---
+
+## replica_html_template rules (Canvas only)
+
+The purpose of replica html template is creating a lightweight version of existing UI so design agent can iterate on top of it (Since superdesign doesn't have access to your codebase directly, this is important context)
+
+Overall process for designing features on top of existing app:
+
+1. Identify & understand existing UI of page related
+2. Create/update a pixel perfect replica html in `.superdesign/replica_html_template/<name>.html` (Only replicate how UI look now, do NOT design)
+
+- If design task is redesign profile page, then replicate current profile page UI pixel perfectly
+- If design task is add new button to side panel, identify which page side panel is using, then replicate that page UI pixel perfectly
+
+**replica_html_template = BEFORE state (what exists now).** It provides context for SuperDesign agent.
+Actual design will be done via superdesign agent, by passing the prompt
+
+The replica_html_template must contain **ONLY UI that currently exists in the codebase**.
+
+- **DO NOT** design or improve anything in the replica_html_template
+- **DO NOT** add placeholder sections like `<!-- NEW FEATURE - DESIGN THIS -->`
+- **DO** create pixel-perfect replica of current UI state
+- Save to: `.superdesign/replica_html_template/<name>.html`
+
+### Naming & Reuse
+
+**Naming convention**
+Name replica_html_template for reusability: Use the page route (e.g., `home.html`, `settings-profile.html`, `dashboard.html`)
+This makes it easy to identify if a page_template already exists.
+
+**Before creating a replica_html_template:**
+
+1. Check if `.superdesign/replica_html_template/` already contains a matching file
+2. If exists: reuse it or update to reflect the latest existing UI
+3. If not exists: create the neww file
+
+### Example: Adding a "Book Demo" section to home page
+
+**BAD approach:**
+
+```html
+<!-- replica_html_template includes a sketched Book Demo section -->
+<section class="book-demo">
+  <!-- DESIGN THIS - Add CTA here -->
+  <h3>Book a Demo</h3>
+  <button>Schedule</button>
+</section>
+```
+
+**GOOD approach:**
+
+```html
+<!-- replica_html_template is pure replica of existing home page (hero + projects) -->
+```
+
+Then in the iterate command:
+1/ create project passing this replica html
+2/ create design draft based on design draft id
+
+---
+
+# 1) Design System Setup
+
+### Step 0 — Ask user (one question)
+
+"Do you want to **create a new design system** or **extract from the current codebase**?"
+
+### A) Extract from codebase
+
+1. Investigate codebase:
+   - Product context: what is being built, target users, core value proposition, key user journeys and page structure
+   - design tokens, typography, colors, spacing, radius, shadows
+   - motion/animation patterns
+   - example components usage + implementation patterns
+2. Write standalone design system to:
+   - `.superdesign/design-system.md`
+   - Must be implementable without the codebase
+
+### B) Create a new design system (to improve current UI)
+
+1. Investigate codebase to understand:
+   - Product context: what is being built, target users, core value proposition, key user journeys and page structure
+   - needed pages/components
+2. Gather inspirations (generic tools):
+   - `superdesign search-prompts --tags "style" --json`
+   - `superdesign get-prompts --slugs ... --json`
+   - optional: `superdesign extract-brand-guide --url ... --json`
+3. Interview user (`askQuestion`) to choose direction
+4. Write:
+   - `.superdesign/design-system.md` (product context + UX flows + visual design, adapted to references)
+
+---
+
+# 2) Designing X (feature/page/flow)
+
+### Example workflow - Add feature to existing page
+
+1. Investigate existing design and Ask targeted questions (`askQuestion`) about requirements + taste
+2. After clarifying, Ask user whether ready to design in superdesign OR implement UI directly
+3. If design in superdesign
+   3.1 Ensure `.superdesign/design-system.md` exists (setup if missing)
+   3.2 Identify page most relevant, and build a pixel-perfect replica in replica_html_template:
+   - `.superdesign/replica_html_template/<page>-<feature>.html`
+     3.3 Create project with replica_html_template (returns `draftId`):
+   ```bash
+   superdesign create-project \
+     --title "<feature>" \
+     --html-file .superdesign/replica_html_template/<file>.html \
+     --set-project-prompt-file .superdesign/design-system.md \
+     --json
+   ```
+   → Note: `draftId` in response is the baseline draft
+   3.4 Branch designs from baseline (use `draftId` from step 3.3)
+   ```bash
+   superdesign iterate-design-draft \
+     --draft-id <draftId> \
+     -p "Dark theme with neon accents" \
+     -p "Minimal with more whitespace" \
+     -p "Bold gradients and shadows" \
+     --mode branch \
+     --json
+   ```
+   3.5 Share design title & preview URL → collect feedback → iterate
+
+### Advanced usage
+
+#### Design multiple page OR a full user journey
+
+Execute:
+
+```bash
+superdesign execute-flow-pages \
+  --draft-id <draftId> \
+  --pages '[{"title":"Signup","prompt":"..."},{"title":"Payment","prompt":"..."}]' \
+  --json
+```
+
+#### Get HTML reference from a draft
+
+```bash
+superdesign get-design --draft-id <draftId> --output ./design.html
+```
+
+---
+
+## Quick reference (key commands)
+
+```bash
+# Inspirations
+superdesign search-prompts --keyword "<keyword>" --json
+superdesign search-prompts --tags "style" --json
+superdesign get-prompts --slugs "<slug1,slug2>" --json
+superdesign extract-brand-guide --url https://example.com --json
+
+# Canvas - Create project
+# Options: -s/--set-project-prompt (inline), --set-project-prompt-file (from file)
+superdesign create-project --title "X" --set-project-prompt "..." --json
+superdesign create-project --title "X" --set-project-prompt-file .superdesign/design-system.md --json
+superdesign create-project --title "X" --html-file ./index.html --set-project-prompt-file .superdesign/design-system.md --json
+
+# Iterate: replace mode (single variation, updates in place)
+superdesign iterate-design-draft --draft-id <id> -p "..." --mode replace --json
+
+# Iterate: Explore multiple versions & variations (each prompt = one variation, prompt should be just directional, do not specify color, style, let superdesign design expert fill in details, you just give direction)
+superdesign iterate-design-draft --draft-id <id> -p "dark theme" -p "minimal" -p "bold" --mode branch --json
+
+# Iterate: Auto explore (only give exploration direction, and let Superdesign fill in details, e.g. explore different styles; Default do not use this)
+superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json
+
+# Fetch & get designs
+superdesign fetch-design-nodes --project-id <id> --json
+superdesign get-design --draft-id <id> --json
+
+# Create new design from scracth without any reference - ONLY use this for creating brand new design, default NEVER use this
+superdesign create-design-draft --project-id <id> --title "X" -p "..." --json
+```

package/dist/config/constants.d.ts

@@ -12,7 +12,10 @@ export declare const POLL_TIMEOUT_MS: number;
 export declare const AUTH_POLL_INTERVAL_MS = 2000;
 export declare const AUTH_POLL_TIMEOUT_MS: number;
 /** CLI version - should match package.json */
-export declare const CLI_VERSION = "0.1.6";
+export declare const CLI_VERSION = "0.1.8";
+/** PostHog analytics configuration */
+export declare const POSTHOG_KEY: string;
+export declare const POSTHOG_HOST: string;
 /** Config directory name */
 export declare const CONFIG_DIR_NAME = ".superdesign";
 /** Config file name */
@@ -31,6 +34,3 @@ export declare const EXIT_CODES: {
 export declare const SKILLS_DIR = ".claude/skills/superdesign";
 /** SKILL.md file name */
 export declare const SKILL_FILE_NAME = "SKILL.md";
-/** PostHog analytics configuration */
-export declare const POSTHOG_KEY: string;
-export declare const POSTHOG_HOST: string;

package/dist/index.cjs

@@ -91,6 +91,8 @@ var __webpack_exports__ = {};
     const external_url_namespaceObject = require("url");
     const external_path_namespaceObject = require("path");
     const external_commander_namespaceObject = require("commander");
+    const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
+    const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
     const CONFIG_DIR_NAME = '.superdesign';
     const CONFIG_FILE_NAME = 'config.json';
     const EXIT_CODES = {
@@ -104,8 +106,6 @@ var __webpack_exports__ = {};
     };
     const SKILLS_DIR = '.claude/skills/superdesign';
     const SKILL_FILE_NAME = 'SKILL.md';
-    const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
-    const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
     const external_fs_namespaceObject = require("fs");
     const external_os_namespaceObject = require("os");
     var external_os_default = /*#__PURE__*/ __webpack_require__.n(external_os_namespaceObject);
@@ -316,7 +316,7 @@ var __webpack_exports__ = {};
         try {
             startSpinner('Creating auth session...');
             const session = await createSession({
-                cliVersion: "0.1.6",
+                cliVersion: "0.1.8",
                 os: `${external_os_namespaceObject.platform()} ${external_os_namespaceObject.release()}`,
                 hostname: external_os_namespaceObject.hostname()
             });
@@ -542,7 +542,7 @@ Action accordingly based on instruction in the guidelines
 
 \`\`\`
 npm install -g @superdesign/cli@latest
-superdesign init
+superdesign login
 superdesign --help
 \`\`\`
 `;
@@ -651,56 +651,45 @@ superdesign --help
     }
     async function runJob(config) {
         const { startLabel, pollingLabel, successLabel, timeoutLabel, failureLabel, timeoutMs = 300000, startJob, transformResult, displayResult } = config;
-        try {
-            startSpinner(startLabel);
-            const job = await startJob();
-            updateSpinner(pollingLabel);
-            const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
-                intervalMs: 2000,
-                timeoutMs,
-                onPoll: (attempt)=>{
-                    if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
-                }
-            });
-            if (pollResult.timedOut) {
-                failSpinner(timeoutLabel);
-                output_error('Job timed out. The operation may still be processing in the background.');
-                if (isJsonMode()) output({
-                    error: 'timeout',
-                    jobId: job.jobId
-                });
-                process.exit(EXIT_CODES.TIMEOUT);
+        startSpinner(startLabel);
+        const job = await startJob();
+        updateSpinner(pollingLabel);
+        const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
+            intervalMs: 2000,
+            timeoutMs,
+            onPoll: (attempt)=>{
+                if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
             }
-            if (!pollResult.success || !pollResult.data) {
-                failSpinner(failureLabel);
-                output_error(pollResult.error || 'Failed to get job status');
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            const jobResult = pollResult.data;
-            if (isJobFailed(jobResult)) {
-                failSpinner(failureLabel);
-                output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            if (!isJobCompleted(jobResult)) {
-                failSpinner('Unexpected job status');
-                output_error('Job ended in unexpected state');
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            succeedSpinner(successLabel);
-            if (isJsonMode()) output(transformResult(jobResult));
-            else displayResult(jobResult);
-            process.exit(EXIT_CODES.SUCCESS);
-        } catch (err) {
+        });
+        if (pollResult.timedOut) {
+            failSpinner(timeoutLabel);
+            if (isJsonMode()) output({
+                error: 'timeout',
+                jobId: job.jobId
+            });
+            else output_error('Job timed out. The operation may still be processing in the background.');
+            throw new ApiClientError('Job timed out', 'timeout');
+        }
+        if (!pollResult.success || !pollResult.data) {
             failSpinner(failureLabel);
-            if (err instanceof ApiClientError) {
-                output_error(`API Error: ${err.message}`);
-                process.exit(EXIT_CODES.API_ERROR);
-            }
-            const message = err instanceof Error ? err.message : 'Unknown error';
-            output_error(message);
-            process.exit(EXIT_CODES.GENERAL_ERROR);
+            const errMsg = pollResult.error || 'Failed to get job status';
+            if (!isJsonMode()) output_error(errMsg);
+            throw new ApiClientError(errMsg, 'api_error');
+        }
+        const jobResult = pollResult.data;
+        if (isJobFailed(jobResult)) {
+            failSpinner(failureLabel);
+            if (!isJsonMode()) output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
+            throw new ApiClientError(jobResult.error.message, jobResult.error.code);
         }
+        if (!isJobCompleted(jobResult)) {
+            failSpinner('Unexpected job status');
+            if (!isJsonMode()) output_error('Job ended in unexpected state');
+            throw new ApiClientError('Job ended in unexpected state', 'unexpected_status');
+        }
+        succeedSpinner(successLabel);
+        if (isJsonMode()) output(transformResult(jobResult));
+        else displayResult(jobResult);
     }
     function job_runner_requireAuth(isAuthenticated) {
         if (!isAuthenticated()) {
@@ -927,9 +916,10 @@ superdesign --help
         return command;
     }
     function createPlanFlowPagesCommand() {
-        const command = new external_commander_namespaceObject.Command('plan-flow-pages').description('Plan flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--source-node-id <id>', 'Source node ID in the flow').option('--context <context>', 'Additional context for flow planning').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('plan-flow-pages').description('Plan flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').option('--context <context>', 'Additional context for flow planning').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
+            const sourceNodeId = `draft-variant-${options.draftId}`;
             await runJob({
                 startLabel: 'Planning flow pages...',
                 pollingLabel: 'AI is analyzing and planning pages...',
@@ -937,7 +927,7 @@ superdesign --help
                 timeoutLabel: 'Planning timed out',
                 failureLabel: 'Failed to plan flow pages',
                 startJob: ()=>planFlowPages(options.draftId, {
-                        sourceNodeId: options.sourceNodeId,
+                        sourceNodeId,
                         flowContext: options.context
                     }),
                 transformResult: (job)=>({
@@ -969,7 +959,7 @@ superdesign --help
         return parsed;
     }
     function createExecuteFlowPagesCommand() {
-        const command = new external_commander_namespaceObject.Command('execute-flow-pages').description('Generate flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--source-node-id <id>', 'Source node ID in the flow').requiredOption('--pages <json>', 'JSON array of pages to generate [{title, prompt}]').option('--context <context>', 'Additional context for flow generation').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('execute-flow-pages').description('Generate flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--pages <json>', 'JSON array of pages to generate [{title, prompt}]').option('--context <context>', 'Additional context for flow generation').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             let pages;
@@ -989,6 +979,7 @@ superdesign --help
                 output_error('Maximum 10 pages allowed');
                 process.exit(EXIT_CODES.VALIDATION_ERROR);
             }
+            const sourceNodeId = `draft-variant-${options.draftId}`;
             const timeoutMs = Math.max(300000, 2 * pages.length * 60000);
             await runJob({
                 startLabel: `Generating ${pages.length} flow page(s)...`,
@@ -998,7 +989,7 @@ superdesign --help
                 failureLabel: 'Failed to execute flow pages',
                 timeoutMs,
                 startJob: ()=>executeFlowPages(options.draftId, {
-                        sourceNodeId: options.sourceNodeId,
+                        sourceNodeId,
                         flowContext: options.context,
                         pages
                     }),
@@ -1286,38 +1277,36 @@ superdesign --help
         });
         return posthogClient;
     }
+    const SENSITIVE_KEYS = [
+        'token',
+        'key',
+        'secret',
+        'password',
+        'apikey',
+        'auth',
+        'authorization',
+        'credential'
+    ];
     function sanitizeOptions(options) {
-        const sensitiveKeys = [
-            'token',
-            'key',
-            'secret',
-            'password',
-            'apiKey',
-            'api_key',
-            'apikey',
-            'auth',
-            'authorization',
-            'credential'
-        ];
         const sanitized = {};
         for (const [key, value] of Object.entries(options)){
+            if ('function' == typeof value || key.startsWith('_')) continue;
             const lowerKey = key.toLowerCase();
-            if (!sensitiveKeys.some((sensitive)=>lowerKey.includes(sensitive))) {
+            if (!SENSITIVE_KEYS.some((sensitive)=>lowerKey.includes(sensitive))) {
                 if ('string' != typeof value || !(value.length > 100)) sanitized[key] = value;
             }
         }
         return sanitized;
     }
     async function trackCommand(opts) {
-        const config = loadConfig();
-        const teamId = config.teamId;
+        const { teamId } = loadConfig();
         const metadata = {
             command: opts.command,
             success: opts.success,
             durationMs: opts.durationMs,
             errorCode: opts.errorCode,
-            options: opts.options ? sanitizeOptions(opts.options) : void 0,
-            cliVersion: "0.1.6",
+            options: opts.options,
+            cliVersion: "0.1.8",
             os: `${external_os_default().platform()} ${external_os_default().release()}`
         };
         const posthog = getPostHog();
@@ -1352,27 +1341,19 @@ superdesign --help
         path: (0, external_path_namespaceObject.resolve)(src_dirname, '../.env')
     });
     (0, external_dotenv_namespaceObject.config)();
-    let commandStartTime = 0;
-    let currentCommand = '';
-    function sanitizeCommandOptions(opts) {
-        const sanitized = {};
-        for (const [key, value] of Object.entries(opts))if (!('function' == typeof value || key.startsWith('_'))) sanitized[key] = value;
-        return sanitized;
-    }
     function createProgram() {
         const program = new external_commander_namespaceObject.Command();
-        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.6");
+        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.8");
+        let startTime = 0;
         program.hook('preAction', ()=>{
-            commandStartTime = Date.now();
-            currentCommand = process.argv[2] || 'unknown';
+            startTime = Date.now();
         });
         program.hook('postAction', async (_thisCommand, actionCommand)=>{
-            const durationMs = Date.now() - commandStartTime;
             await trackCommand({
-                command: currentCommand,
+                command: actionCommand.name(),
                 success: true,
-                durationMs,
-                options: sanitizeCommandOptions(actionCommand.opts())
+                durationMs: Date.now() - startTime,
+                options: sanitizeOptions(actionCommand.opts())
             });
             await shutdownAnalytics();
         });

package/dist/index.js

@@ -8,6 +8,8 @@ import axios from "axios";
 import ora from "ora";
 import { writeFile } from "fs/promises";
 import { PostHog } from "posthog-node";
+const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
+const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
 const CONFIG_DIR_NAME = '.superdesign';
 const CONFIG_FILE_NAME = 'config.json';
 const EXIT_CODES = {
@@ -21,8 +23,6 @@ const EXIT_CODES = {
 };
 const SKILLS_DIR = '.claude/skills/superdesign';
 const SKILL_FILE_NAME = 'SKILL.md';
-const POSTHOG_KEY = process.env.POSTHOG_KEY || 'phc_oUcDklFBX3wy8eksSyEC0pataKCgSadur1sio5hBHg4';
-const POSTHOG_HOST = process.env.POSTHOG_HOST || 'https://eu.i.posthog.com';
 function getConfigDir() {
     return join(homedir(), CONFIG_DIR_NAME);
 }
@@ -226,7 +226,7 @@ async function runAuthFlow(options = {}) {
     try {
         startSpinner('Creating auth session...');
         const session = await createSession({
-            cliVersion: "0.1.6",
+            cliVersion: "0.1.8",
             os: `${platform()} ${release()}`,
             hostname: hostname()
         });
@@ -452,7 +452,7 @@ Action accordingly based on instruction in the guidelines
 
 \`\`\`
 npm install -g @superdesign/cli@latest
-superdesign init
+superdesign login
 superdesign --help
 \`\`\`
 `;
@@ -561,56 +561,45 @@ function isJobFailed(response) {
 }
 async function runJob(config) {
     const { startLabel, pollingLabel, successLabel, timeoutLabel, failureLabel, timeoutMs = 300000, startJob, transformResult, displayResult } = config;
-    try {
-        startSpinner(startLabel);
-        const job = await startJob();
-        updateSpinner(pollingLabel);
-        const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
-            intervalMs: 2000,
-            timeoutMs,
-            onPoll: (attempt)=>{
-                if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
-            }
-        });
-        if (pollResult.timedOut) {
-            failSpinner(timeoutLabel);
-            output_error('Job timed out. The operation may still be processing in the background.');
-            if (isJsonMode()) output({
-                error: 'timeout',
-                jobId: job.jobId
-            });
-            process.exit(EXIT_CODES.TIMEOUT);
+    startSpinner(startLabel);
+    const job = await startJob();
+    updateSpinner(pollingLabel);
+    const pollResult = await poll(()=>getJobStatus(job.jobId), isJobDone, {
+        intervalMs: 2000,
+        timeoutMs,
+        onPoll: (attempt)=>{
+            if (attempt % 5 === 0) updateSpinner(`${pollingLabel} (${Math.floor(2000 * attempt / 1000)}s)`);
         }
-        if (!pollResult.success || !pollResult.data) {
-            failSpinner(failureLabel);
-            output_error(pollResult.error || 'Failed to get job status');
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        const jobResult = pollResult.data;
-        if (isJobFailed(jobResult)) {
-            failSpinner(failureLabel);
-            output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        if (!isJobCompleted(jobResult)) {
-            failSpinner('Unexpected job status');
-            output_error('Job ended in unexpected state');
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        succeedSpinner(successLabel);
-        if (isJsonMode()) output(transformResult(jobResult));
-        else displayResult(jobResult);
-        process.exit(EXIT_CODES.SUCCESS);
-    } catch (err) {
+    });
+    if (pollResult.timedOut) {
+        failSpinner(timeoutLabel);
+        if (isJsonMode()) output({
+            error: 'timeout',
+            jobId: job.jobId
+        });
+        else output_error('Job timed out. The operation may still be processing in the background.');
+        throw new ApiClientError('Job timed out', 'timeout');
+    }
+    if (!pollResult.success || !pollResult.data) {
         failSpinner(failureLabel);
-        if (err instanceof ApiClientError) {
-            output_error(`API Error: ${err.message}`);
-            process.exit(EXIT_CODES.API_ERROR);
-        }
-        const message = err instanceof Error ? err.message : 'Unknown error';
-        output_error(message);
-        process.exit(EXIT_CODES.GENERAL_ERROR);
+        const errMsg = pollResult.error || 'Failed to get job status';
+        if (!isJsonMode()) output_error(errMsg);
+        throw new ApiClientError(errMsg, 'api_error');
+    }
+    const jobResult = pollResult.data;
+    if (isJobFailed(jobResult)) {
+        failSpinner(failureLabel);
+        if (!isJsonMode()) output_error(`${jobResult.error.code}: ${jobResult.error.message}`);
+        throw new ApiClientError(jobResult.error.message, jobResult.error.code);
     }
+    if (!isJobCompleted(jobResult)) {
+        failSpinner('Unexpected job status');
+        if (!isJsonMode()) output_error('Job ended in unexpected state');
+        throw new ApiClientError('Job ended in unexpected state', 'unexpected_status');
+    }
+    succeedSpinner(successLabel);
+    if (isJsonMode()) output(transformResult(jobResult));
+    else displayResult(jobResult);
 }
 function job_runner_requireAuth(isAuthenticated) {
     if (!isAuthenticated()) {
@@ -837,9 +826,10 @@ function createIterateDesignDraftCommand() {
     return command;
 }
 function createPlanFlowPagesCommand() {
-    const command = new Command('plan-flow-pages').description('Plan flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--source-node-id <id>', 'Source node ID in the flow').option('--context <context>', 'Additional context for flow planning').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('plan-flow-pages').description('Plan flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').option('--context <context>', 'Additional context for flow planning').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
+        const sourceNodeId = `draft-variant-${options.draftId}`;
         await runJob({
             startLabel: 'Planning flow pages...',
             pollingLabel: 'AI is analyzing and planning pages...',
@@ -847,7 +837,7 @@ function createPlanFlowPagesCommand() {
             timeoutLabel: 'Planning timed out',
             failureLabel: 'Failed to plan flow pages',
             startJob: ()=>planFlowPages(options.draftId, {
-                    sourceNodeId: options.sourceNodeId,
+                    sourceNodeId,
                     flowContext: options.context
                 }),
             transformResult: (job)=>({
@@ -879,7 +869,7 @@ function parsePages(pagesJson) {
     return parsed;
 }
 function createExecuteFlowPagesCommand() {
-    const command = new Command('execute-flow-pages').description('Generate flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--source-node-id <id>', 'Source node ID in the flow').requiredOption('--pages <json>', 'JSON array of pages to generate [{title, prompt}]').option('--context <context>', 'Additional context for flow generation').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('execute-flow-pages').description('Generate flow pages using AI').requiredOption('--draft-id <id>', 'Source draft ID').requiredOption('--pages <json>', 'JSON array of pages to generate [{title, prompt}]').option('--context <context>', 'Additional context for flow generation').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         let pages;
@@ -899,6 +889,7 @@ function createExecuteFlowPagesCommand() {
             output_error('Maximum 10 pages allowed');
             process.exit(EXIT_CODES.VALIDATION_ERROR);
         }
+        const sourceNodeId = `draft-variant-${options.draftId}`;
         const timeoutMs = Math.max(300000, 2 * pages.length * 60000);
         await runJob({
             startLabel: `Generating ${pages.length} flow page(s)...`,
@@ -908,7 +899,7 @@ function createExecuteFlowPagesCommand() {
             failureLabel: 'Failed to execute flow pages',
             timeoutMs,
             startJob: ()=>executeFlowPages(options.draftId, {
-                    sourceNodeId: options.sourceNodeId,
+                    sourceNodeId,
                     flowContext: options.context,
                     pages
                 }),
@@ -1194,38 +1185,36 @@ function getPostHog() {
     });
     return posthogClient;
 }
+const SENSITIVE_KEYS = [
+    'token',
+    'key',
+    'secret',
+    'password',
+    'apikey',
+    'auth',
+    'authorization',
+    'credential'
+];
 function sanitizeOptions(options) {
-    const sensitiveKeys = [
-        'token',
-        'key',
-        'secret',
-        'password',
-        'apiKey',
-        'api_key',
-        'apikey',
-        'auth',
-        'authorization',
-        'credential'
-    ];
     const sanitized = {};
     for (const [key, value] of Object.entries(options)){
+        if ('function' == typeof value || key.startsWith('_')) continue;
         const lowerKey = key.toLowerCase();
-        if (!sensitiveKeys.some((sensitive)=>lowerKey.includes(sensitive))) {
+        if (!SENSITIVE_KEYS.some((sensitive)=>lowerKey.includes(sensitive))) {
             if ('string' != typeof value || !(value.length > 100)) sanitized[key] = value;
         }
     }
     return sanitized;
 }
 async function trackCommand(opts) {
-    const config = loadConfig();
-    const teamId = config.teamId;
+    const { teamId } = loadConfig();
     const metadata = {
         command: opts.command,
         success: opts.success,
         durationMs: opts.durationMs,
         errorCode: opts.errorCode,
-        options: opts.options ? sanitizeOptions(opts.options) : void 0,
-        cliVersion: "0.1.6",
+        options: opts.options,
+        cliVersion: "0.1.8",
         os: `${os.platform()} ${os.release()}`
     };
     const posthog = getPostHog();
@@ -1260,27 +1249,19 @@ external_dotenv_config({
     path: external_path_resolve(src_dirname, '../.env')
 });
 external_dotenv_config();
-let commandStartTime = 0;
-let currentCommand = '';
-function sanitizeCommandOptions(opts) {
-    const sanitized = {};
-    for (const [key, value] of Object.entries(opts))if (!('function' == typeof value || key.startsWith('_'))) sanitized[key] = value;
-    return sanitized;
-}
 function createProgram() {
     const program = new Command();
-    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.6");
+    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.8");
+    let startTime = 0;
     program.hook('preAction', ()=>{
-        commandStartTime = Date.now();
-        currentCommand = process.argv[2] || 'unknown';
+        startTime = Date.now();
     });
     program.hook('postAction', async (_thisCommand, actionCommand)=>{
-        const durationMs = Date.now() - commandStartTime;
         await trackCommand({
-            command: currentCommand,
+            command: actionCommand.name(),
             success: true,
-            durationMs,
-            options: sanitizeCommandOptions(actionCommand.opts())
+            durationMs: Date.now() - startTime,
+            options: sanitizeOptions(actionCommand.opts())
         });
         await shutdownAnalytics();
     });

package/dist/utils/analytics.d.ts

@@ -9,9 +9,9 @@ export interface TrackCommandOptions {
     options?: Record<string, unknown>;
 }
 /**
- * Sanitize command options to remove sensitive values
+ * Sanitize command options by removing sensitive values, functions, and internal properties
  */
-declare function sanitizeOptions(options: Record<string, unknown>): Record<string, unknown>;
+export declare function sanitizeOptions(options: Record<string, unknown>): Record<string, unknown>;
 /**
  * Track a CLI command execution
  * Sends to both PostHog (real-time dashboards) and backend (long-term storage)
@@ -22,4 +22,3 @@ export declare function trackCommand(opts: TrackCommandOptions): Promise<void>;
  * Should be called before CLI exits
  */
 export declare function shutdownAnalytics(): Promise<void>;
-export { sanitizeOptions };

package/dist/utils/job-runner.d.ts

@@ -33,8 +33,9 @@ export interface JobRunnerResult<TResult> {
 /**
  * Run a job with polling and standard error handling
  * Handles spinner updates, timeout, failure states, and output formatting
+ * Returns normally on success, throws on failure (to allow postAction hooks to run)
  */
-export declare function runJob<TResult>(config: JobRunnerConfig<TResult>): Promise<never>;
+export declare function runJob<TResult>(config: JobRunnerConfig<TResult>): Promise<void>;
 /**
  * Check authentication and exit with appropriate error if not authenticated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdesign/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "CLI for SuperDesign Platform - agent skills for Claude Code",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,13 +20,17 @@
     "dist",
     "bin"
   ],
+  "scripts": {
+    "build": "rslib build && chmod +x bin/superdesign.js",
+    "dev": "rslib build --watch"
+  },
   "dependencies": {
     "axios": "^1.6.0",
     "commander": "^11.1.0",
     "dotenv": "^16.3.0",
     "open": "^10.0.0",
     "ora": "^8.0.0",
-    "posthog-node": "^4.0.0"
+    "posthog-node": "^5.24.1"
   },
   "devDependencies": {
     "@rslib/core": "0.15.1",
@@ -48,9 +52,5 @@
     "url": "https://github.com/superdesigndev/superdesign-platform.git",
     "directory": "packages/cli"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "rslib build && chmod +x bin/superdesign.js",
-    "dev": "rslib build --watch"
-  }
-}
+  "license": "MIT"
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Super Design
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.