@superdesign/cli 0.1.13 → 0.2.1

package/dist/api/drafts.d.ts

@@ -1,16 +1,22 @@
 /**
  * Drafts API endpoints
  */
+export interface ContextFile {
+    filename: string;
+    content: string;
+}
 export interface CreateDraftRequest {
     title: string;
     prompt: string;
     deviceMode?: 'mobile' | 'tablet' | 'desktop';
+    contextFiles?: ContextFile[];
 }
 export interface IterateDraftRequest {
     prompts?: string[];
     prompt?: string;
     count?: 1 | 2 | 3 | 4;
     mode: 'replace' | 'branch';
+    contextFiles?: ContextFile[];
 }
 export interface PlanFlowRequest {
     flowContext?: string;
@@ -22,6 +28,7 @@ export interface FlowPage {
 export interface ExecuteFlowRequest {
     flowContext?: string;
     pages: FlowPage[];
+    contextFiles?: ContextFile[];
 }
 export interface JobCreatedResponse {
     jobId: string;

package/dist/config/constants.d.ts

@@ -12,7 +12,7 @@ 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.13";
+export declare const CLI_VERSION = "0.2.1";
 /** PostHog analytics configuration */
 export declare const POSTHOG_KEY: string;
 export declare const POSTHOG_HOST: string;

package/dist/index.cjs

@@ -316,7 +316,7 @@ var __webpack_exports__ = {};
         try {
             startSpinner('Creating auth session...');
             const session = await createSession({
-                cliVersion: "0.1.13",
+                cliVersion: "0.2.1",
                 os: `${external_os_namespaceObject.platform()} ${external_os_namespaceObject.release()}`,
                 hostname: external_os_namespaceObject.hostname()
             });
@@ -799,11 +799,140 @@ superdesign --help
         const response = await client.post(`/external/drafts/${draftId}/flow/execute`, data);
         return response.data;
     }
+    function parseContextFileArg(arg) {
+        const match = arg.match(/^(.+?):(\d+)(?::(\d+))?$/);
+        if (!match) return {
+            rawPath: arg
+        };
+        const [, pathPart, startStr, endStr] = match;
+        const startLine = parseInt(startStr, 10);
+        const endLine = void 0 !== endStr ? parseInt(endStr, 10) : void 0;
+        if (startLine < 1) {
+            output_error(`Invalid line range in "${arg}": start line must be >= 1`);
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
+        }
+        if (void 0 !== endLine && endLine < startLine) {
+            output_error(`Invalid line range in "${arg}": end line (${endLine}) must be >= start line (${startLine})`);
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
+        }
+        const cwd = process.cwd();
+        const extractedAbsolute = (0, external_path_namespaceObject.resolve)(cwd, pathPart);
+        const originalAbsolute = (0, external_path_namespaceObject.resolve)(cwd, arg);
+        if (!(0, external_fs_namespaceObject.existsSync)(extractedAbsolute) && (0, external_fs_namespaceObject.existsSync)(originalAbsolute)) return {
+            rawPath: arg
+        };
+        return {
+            rawPath: pathPart,
+            startLine,
+            endLine
+        };
+    }
+    function extractLines(content, start, end) {
+        const lines = content.split('\n');
+        const from = Math.max(0, start - 1);
+        const to = Math.min(lines.length, end);
+        return lines.slice(from, to).join('\n');
+    }
+    function mergeRanges(ranges) {
+        if (0 === ranges.length) return [];
+        const sorted = [
+            ...ranges
+        ].sort((a, b)=>a.start - b.start);
+        const merged = [
+            sorted[0]
+        ];
+        for(let i = 1; i < sorted.length; i++){
+            const prev = merged[merged.length - 1];
+            const curr = sorted[i];
+            if (prev.end >= curr.start - 1 || prev.end === 1 / 0) prev.end = Math.max(prev.end, curr.end);
+            else merged.push({
+                ...curr
+            });
+        }
+        return merged;
+    }
+    function formatRangeContent(content, ranges) {
+        const totalLines = content.split('\n').length;
+        const parts = [];
+        for(let i = 0; i < ranges.length; i++){
+            const range = ranges[i];
+            const effectiveEnd = range.end === 1 / 0 ? totalLines : Math.min(range.end, totalLines);
+            if (i > 0) {
+                const prevEnd = ranges[i - 1].end === 1 / 0 ? totalLines : Math.min(ranges[i - 1].end, totalLines);
+                const gapStart = prevEnd + 1;
+                const gapEnd = range.start - 1;
+                if (gapEnd >= gapStart) {
+                    const gapSize = gapEnd - gapStart + 1;
+                    parts.push(`// ... (lines ${gapStart}-${gapEnd} omitted, ${gapSize} lines) ...`);
+                }
+            }
+            parts.push(`// === Lines ${range.start}-${effectiveEnd} ===`);
+            parts.push(extractLines(content, range.start, effectiveEnd));
+        }
+        return parts.join('\n');
+    }
+    function readContextFiles(filePaths) {
+        const cwd = process.cwd();
+        const refs = filePaths.map(parseContextFileArg);
+        const groups = new Map();
+        for (const ref of refs){
+            const absolutePath = (0, external_path_namespaceObject.resolve)(cwd, ref.rawPath);
+            const relPath = (0, external_path_namespaceObject.relative)(cwd, absolutePath);
+            let group = groups.get(absolutePath);
+            if (!group) {
+                group = {
+                    relPath,
+                    fullFile: false,
+                    ranges: []
+                };
+                groups.set(absolutePath, group);
+            }
+            if (void 0 === ref.startLine) group.fullFile = true;
+            else group.ranges.push({
+                start: ref.startLine,
+                end: ref.endLine ?? 1 / 0
+            });
+        }
+        const results = [];
+        for (const [absolutePath, group] of groups){
+            let content;
+            try {
+                content = (0, external_fs_namespaceObject.readFileSync)(absolutePath, 'utf-8');
+            } catch (err) {
+                const msg = err instanceof Error ? err.message : 'Unknown error';
+                output_error(`Failed to read context file "${group.relPath}": ${msg}`);
+                process.exit(EXIT_CODES.VALIDATION_ERROR);
+            }
+            if (group.fullFile || 0 === group.ranges.length) {
+                results.push({
+                    filename: group.relPath,
+                    content
+                });
+                continue;
+            }
+            const merged = mergeRanges(group.ranges);
+            const totalLines = content.split('\n').length;
+            if (1 === merged.length && merged[0].start <= 1 && (merged[0].end === 1 / 0 || merged[0].end >= totalLines)) {
+                results.push({
+                    filename: group.relPath,
+                    content
+                });
+                continue;
+            }
+            const formatted = formatRangeContent(content, merged);
+            results.push({
+                filename: group.relPath,
+                content: formatted
+            });
+        }
+        return results;
+    }
     function createCreateDesignDraftCommand() {
-        const command = new external_commander_namespaceObject.Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
+        const command = new external_commander_namespaceObject.Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             validateDeviceMode(options.device);
+            const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
             await runJob({
                 startLabel: 'Creating design draft...',
                 pollingLabel: 'Generating design with AI...',
@@ -813,7 +942,8 @@ superdesign --help
                 startJob: ()=>createDraft(options.projectId, {
                         title: options.title,
                         prompt: options.prompt,
-                        deviceMode: options.device
+                        deviceMode: options.device,
+                        contextFiles
                     }),
                 transformResult: (job)=>({
                         draftId: job.result.draftId,
@@ -885,17 +1015,20 @@ Usage Examples:
   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 auto explore mode)
-  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').addOption(new external_commander_namespaceObject.Option('--project-id <id>').hideHelp()).action(async (options)=>{
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').addOption(new external_commander_namespaceObject.Option('--project-id <id>').hideHelp()).action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             const { prompts, count, mode } = validateOptions(options);
+            const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
             const requestData = prompts.length > 1 ? {
                 prompts,
-                mode
+                mode,
+                contextFiles
             } : {
                 prompt: prompts[0],
                 count: count,
-                mode
+                mode,
+                contextFiles
             };
             await runJob({
                 startLabel: 'Starting iteration...',
@@ -966,7 +1099,7 @@ Usage Examples:
         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('--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('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').action(async (options)=>{
             if (options.json) setJsonMode(true);
             job_runner_requireAuth(manager_isAuthenticated);
             let pages;
@@ -986,6 +1119,7 @@ Usage Examples:
                 output_error('Maximum 10 pages allowed');
                 process.exit(EXIT_CODES.VALIDATION_ERROR);
             }
+            const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
             const timeoutMs = Math.max(300000, 2 * pages.length * 60000);
             await runJob({
                 startLabel: `Generating ${pages.length} flow page(s)...`,
@@ -996,7 +1130,8 @@ Usage Examples:
                 timeoutMs,
                 startJob: ()=>executeFlowPages(options.draftId, {
                         flowContext: options.context,
-                        pages
+                        pages,
+                        contextFiles
                     }),
                 transformResult: (job)=>({
                         drafts: job.result.drafts,
@@ -1311,7 +1446,7 @@ Usage Examples:
             durationMs: opts.durationMs,
             errorCode: opts.errorCode,
             options: opts.options,
-            cliVersion: "0.1.13",
+            cliVersion: "0.2.1",
             os: `${external_os_default().platform()} ${external_os_default().release()}`
         };
         const posthog = getPostHog();
@@ -1379,7 +1514,7 @@ Usage Examples:
     }
     function createProgram() {
         const program = new external_commander_namespaceObject.Command();
-        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.13");
+        program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.2.1");
         program.configureOutput({
             writeErr: (str)=>{
                 if (!process.argv.includes('--json')) process.stderr.write(str);

package/dist/index.js

@@ -1,6 +1,6 @@
 import { config as external_dotenv_config } from "dotenv";
 import { fileURLToPath } from "url";
-import { dirname, join, resolve as external_path_resolve } from "path";
+import { dirname, join, relative, resolve as external_path_resolve } from "path";
 import { Command, Option } from "commander";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import os, { homedir, hostname, platform, release } from "os";
@@ -226,7 +226,7 @@ async function runAuthFlow(options = {}) {
     try {
         startSpinner('Creating auth session...');
         const session = await createSession({
-            cliVersion: "0.1.13",
+            cliVersion: "0.2.1",
             os: `${platform()} ${release()}`,
             hostname: hostname()
         });
@@ -709,11 +709,140 @@ async function executeFlowPages(draftId, data) {
     const response = await client.post(`/external/drafts/${draftId}/flow/execute`, data);
     return response.data;
 }
+function parseContextFileArg(arg) {
+    const match = arg.match(/^(.+?):(\d+)(?::(\d+))?$/);
+    if (!match) return {
+        rawPath: arg
+    };
+    const [, pathPart, startStr, endStr] = match;
+    const startLine = parseInt(startStr, 10);
+    const endLine = void 0 !== endStr ? parseInt(endStr, 10) : void 0;
+    if (startLine < 1) {
+        output_error(`Invalid line range in "${arg}": start line must be >= 1`);
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    if (void 0 !== endLine && endLine < startLine) {
+        output_error(`Invalid line range in "${arg}": end line (${endLine}) must be >= start line (${startLine})`);
+        process.exit(EXIT_CODES.VALIDATION_ERROR);
+    }
+    const cwd = process.cwd();
+    const extractedAbsolute = external_path_resolve(cwd, pathPart);
+    const originalAbsolute = external_path_resolve(cwd, arg);
+    if (!existsSync(extractedAbsolute) && existsSync(originalAbsolute)) return {
+        rawPath: arg
+    };
+    return {
+        rawPath: pathPart,
+        startLine,
+        endLine
+    };
+}
+function extractLines(content, start, end) {
+    const lines = content.split('\n');
+    const from = Math.max(0, start - 1);
+    const to = Math.min(lines.length, end);
+    return lines.slice(from, to).join('\n');
+}
+function mergeRanges(ranges) {
+    if (0 === ranges.length) return [];
+    const sorted = [
+        ...ranges
+    ].sort((a, b)=>a.start - b.start);
+    const merged = [
+        sorted[0]
+    ];
+    for(let i = 1; i < sorted.length; i++){
+        const prev = merged[merged.length - 1];
+        const curr = sorted[i];
+        if (prev.end >= curr.start - 1 || prev.end === 1 / 0) prev.end = Math.max(prev.end, curr.end);
+        else merged.push({
+            ...curr
+        });
+    }
+    return merged;
+}
+function formatRangeContent(content, ranges) {
+    const totalLines = content.split('\n').length;
+    const parts = [];
+    for(let i = 0; i < ranges.length; i++){
+        const range = ranges[i];
+        const effectiveEnd = range.end === 1 / 0 ? totalLines : Math.min(range.end, totalLines);
+        if (i > 0) {
+            const prevEnd = ranges[i - 1].end === 1 / 0 ? totalLines : Math.min(ranges[i - 1].end, totalLines);
+            const gapStart = prevEnd + 1;
+            const gapEnd = range.start - 1;
+            if (gapEnd >= gapStart) {
+                const gapSize = gapEnd - gapStart + 1;
+                parts.push(`// ... (lines ${gapStart}-${gapEnd} omitted, ${gapSize} lines) ...`);
+            }
+        }
+        parts.push(`// === Lines ${range.start}-${effectiveEnd} ===`);
+        parts.push(extractLines(content, range.start, effectiveEnd));
+    }
+    return parts.join('\n');
+}
+function readContextFiles(filePaths) {
+    const cwd = process.cwd();
+    const refs = filePaths.map(parseContextFileArg);
+    const groups = new Map();
+    for (const ref of refs){
+        const absolutePath = external_path_resolve(cwd, ref.rawPath);
+        const relPath = relative(cwd, absolutePath);
+        let group = groups.get(absolutePath);
+        if (!group) {
+            group = {
+                relPath,
+                fullFile: false,
+                ranges: []
+            };
+            groups.set(absolutePath, group);
+        }
+        if (void 0 === ref.startLine) group.fullFile = true;
+        else group.ranges.push({
+            start: ref.startLine,
+            end: ref.endLine ?? 1 / 0
+        });
+    }
+    const results = [];
+    for (const [absolutePath, group] of groups){
+        let content;
+        try {
+            content = readFileSync(absolutePath, 'utf-8');
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : 'Unknown error';
+            output_error(`Failed to read context file "${group.relPath}": ${msg}`);
+            process.exit(EXIT_CODES.VALIDATION_ERROR);
+        }
+        if (group.fullFile || 0 === group.ranges.length) {
+            results.push({
+                filename: group.relPath,
+                content
+            });
+            continue;
+        }
+        const merged = mergeRanges(group.ranges);
+        const totalLines = content.split('\n').length;
+        if (1 === merged.length && merged[0].start <= 1 && (merged[0].end === 1 / 0 || merged[0].end >= totalLines)) {
+            results.push({
+                filename: group.relPath,
+                content
+            });
+            continue;
+        }
+        const formatted = formatRangeContent(content, merged);
+        results.push({
+            filename: group.relPath,
+            content: formatted
+        });
+    }
+    return results;
+}
 function createCreateDesignDraftCommand() {
-    const command = new Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--json', 'Output in JSON format').action(async (options)=>{
+    const command = new Command('create-design-draft').description('Create a design draft from scratch without any reference, Default dont use this, use iterate-design-draft instead').requiredOption('--project-id <id>', 'Project ID').requiredOption('--title <title>', 'Draft title').requiredOption('-p, --prompt <prompt>', 'Design prompt for AI generation').option('--device <mode>', 'Device mode (mobile, tablet, desktop)', 'desktop').option('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         validateDeviceMode(options.device);
+        const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
         await runJob({
             startLabel: 'Creating design draft...',
             pollingLabel: 'Generating design with AI...',
@@ -723,7 +852,8 @@ function createCreateDesignDraftCommand() {
             startJob: ()=>createDraft(options.projectId, {
                     title: options.title,
                     prompt: options.prompt,
-                    deviceMode: options.device
+                    deviceMode: options.device,
+                    contextFiles
                 }),
             transformResult: (job)=>({
                     draftId: job.result.draftId,
@@ -795,17 +925,20 @@ Usage Examples:
   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 auto explore mode)
-  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--json', 'Output in JSON format').addOption(new Option('--project-id <id>').hideHelp()).action(async (options)=>{
+  superdesign iterate-design-draft --draft-id <id> -p "..." --mode branch --count 3 --json`).requiredOption('--draft-id <id>', 'Draft ID to iterate on').requiredOption('-p, --prompt <prompt...>', 'Iteration prompt(s). Use multiple -p for specific prompts per variation.').requiredOption('--mode <mode>', 'Iteration mode (replace or branch)').option('--count <count>', 'Number of variations (1-4). Only used when single prompt provided.').option('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').addOption(new Option('--project-id <id>').hideHelp()).action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         const { prompts, count, mode } = validateOptions(options);
+        const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
         const requestData = prompts.length > 1 ? {
             prompts,
-            mode
+            mode,
+            contextFiles
         } : {
             prompt: prompts[0],
             count: count,
-            mode
+            mode,
+            contextFiles
         };
         await runJob({
             startLabel: 'Starting iteration...',
@@ -876,7 +1009,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('--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('--context-file <paths...>', 'UI source files to include as context for AI generation').option('--json', 'Output in JSON format').action(async (options)=>{
         if (options.json) setJsonMode(true);
         job_runner_requireAuth(manager_isAuthenticated);
         let pages;
@@ -896,6 +1029,7 @@ function createExecuteFlowPagesCommand() {
             output_error('Maximum 10 pages allowed');
             process.exit(EXIT_CODES.VALIDATION_ERROR);
         }
+        const contextFiles = options.contextFile ? readContextFiles(options.contextFile) : void 0;
         const timeoutMs = Math.max(300000, 2 * pages.length * 60000);
         await runJob({
             startLabel: `Generating ${pages.length} flow page(s)...`,
@@ -906,7 +1040,8 @@ function createExecuteFlowPagesCommand() {
             timeoutMs,
             startJob: ()=>executeFlowPages(options.draftId, {
                     flowContext: options.context,
-                    pages
+                    pages,
+                    contextFiles
                 }),
             transformResult: (job)=>({
                     drafts: job.result.drafts,
@@ -1219,7 +1354,7 @@ async function trackCommand(opts) {
         durationMs: opts.durationMs,
         errorCode: opts.errorCode,
         options: opts.options,
-        cliVersion: "0.1.13",
+        cliVersion: "0.2.1",
         os: `${os.platform()} ${os.release()}`
     };
     const posthog = getPostHog();
@@ -1287,7 +1422,7 @@ function findFailedCommand(program) {
 }
 function createProgram() {
     const program = new Command();
-    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.1.13");
+    program.name('superdesign').description('SuperDesign CLI - AI product designer for coding agents').version("0.2.1");
     program.configureOutput({
         writeErr: (str)=>{
             if (!process.argv.includes('--json')) process.stderr.write(str);

package/dist/utils/context-files.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Utilities for reading context files from disk.
+ *
+ * Supports optional line-range syntax:
+ *   path              → full file
+ *   path:startLine    → from startLine to end-of-file  (1-based)
+ *   path:start:end    → lines start–end inclusive       (1-based)
+ *
+ * Multiple ranges from the same file are merged into a single ContextFile
+ * with omission markers between non-contiguous ranges.
+ */
+import type { ContextFile } from '../api/drafts';
+/** A parsed reference to a file with an optional line range. */
+interface ParsedFileRef {
+    /** Raw path as the user typed it (before resolution). */
+    rawPath: string;
+    /** Start line (1-based, inclusive). `undefined` means "from the beginning". */
+    startLine?: number;
+    /** End line (1-based, inclusive). `undefined` means "to the end of the file". */
+    endLine?: number;
+}
+/** Normalised, validated range ready for slicing. */
+interface LineRange {
+    start: number;
+    end: number;
+}
+/**
+ * Parse a `--context-file` argument into a path and optional line range.
+ *
+ * Accepted forms:
+ *   "src/App.tsx"         → { rawPath: "src/App.tsx" }
+ *   "src/App.tsx:10:50"   → { rawPath: "src/App.tsx", startLine: 10, endLine: 50 }
+ *   "src/App.tsx:10"      → { rawPath: "src/App.tsx", startLine: 10 }
+ *
+ * Windows paths (C:\foo\bar.ts) are handled: we only split on the
+ * *last* colon-separated numeric segments.
+ */
+export declare function parseContextFileArg(arg: string): ParsedFileRef;
+/**
+ * Extract a range of lines from content.
+ * Both `start` and `end` are 1-based inclusive.
+ * If `end` exceeds total lines the result is clamped.
+ */
+export declare function extractLines(content: string, start: number, end: number): string;
+/**
+ * Merge overlapping or adjacent line ranges.
+ * Input ranges do not need to be sorted.
+ * Returns sorted, non-overlapping ranges.
+ */
+export declare function mergeRanges(ranges: LineRange[]): LineRange[];
+/**
+ * Build annotated content for multiple line ranges from a single file.
+ *
+ * Each range gets a `// === Lines X-Y ===` header.
+ * Gaps between ranges get `// ... (lines X-Y omitted, N lines) ...` markers.
+ */
+export declare function formatRangeContent(content: string, ranges: LineRange[]): string;
+/**
+ * Read context files from disk and return as ContextFile array.
+ *
+ * Supports `path:startLine:endLine` syntax. Multiple references to the
+ * same file are aggregated: the file is read once and ranges are merged.
+ *
+ * If any file has *both* a full-file reference and partial ranges, the
+ * full file content wins (no annotations).
+ *
+ * Exits the process if any file cannot be read.
+ */
+export declare function readContextFiles(filePaths: string[]): ContextFile[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdesign/cli",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "CLI for SuperDesign Platform - agent skills for Claude Code",
   "type": "module",
   "main": "./dist/index.cjs",