@meltstudio/meltctl 4.23.1 → 4.24.1

package/dist/commands/init.js

@@ -65,6 +65,16 @@ description: >-
   report with scores and actionable fixes.
 ---
 
+`,
+    'ux-audit': `---
+user-invocable: true
+description: >-
+  Review the project's UI against usability heuristics using Chrome DevTools
+  MCP. Use when the developer wants to check UX quality, says "review the UI",
+  or "UX audit". In full audit mode, crawls the entire app. During an active
+  plan, scopes to the current feature and appends results to the plan file.
+---
+
 `,
     validate: `---
 user-invocable: true
@@ -128,6 +138,11 @@ description: Systematically investigate and fix bugs.
 description: Run a comprehensive project compliance audit against team standards.
 ---
 
+`,
+    'ux-audit': `---
+description: Review the project's UI against usability heuristics using Chrome DevTools MCP.
+---
+
 `,
     validate: `---
 description: Run the validation plan from the plan document after implementation.
@@ -286,6 +301,7 @@ export async function initCommand(options) {
         'pr',
         'debug',
         'audit',
+        'ux-audit',
         'update',
         'help',
     ];
@@ -320,7 +336,7 @@ export async function initCommand(options) {
                 await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillContent, 'utf-8');
             }
         }
-        createdFiles.push('.claude/skills/melt-{setup,plan,validate,review,pr,debug,audit,update,help}/SKILL.md');
+        createdFiles.push('.claude/skills/melt-{setup,plan,validate,review,pr,debug,audit,ux-audit,update,help}/SKILL.md');
     }
     // Cursor files
     if (tools.cursor) {
@@ -331,7 +347,7 @@ export async function initCommand(options) {
                 await fs.writeFile(path.join(cwd, `.cursor/commands/melt-${name}.md`), workflowContent, 'utf-8');
             }
         }
-        createdFiles.push('.cursor/commands/melt-{setup,plan,validate,review,pr,debug,audit,update,help}.md');
+        createdFiles.push('.cursor/commands/melt-{setup,plan,validate,review,pr,debug,audit,ux-audit,update,help}.md');
     }
     // OpenCode files
     if (tools.opencode) {
@@ -343,7 +359,7 @@ export async function initCommand(options) {
                 await fs.writeFile(path.join(cwd, `.opencode/commands/melt-${name}.md`), commandContent, 'utf-8');
             }
         }
-        createdFiles.push('.opencode/commands/melt-{setup,plan,validate,review,pr,debug,audit,update,help}.md');
+        createdFiles.push('.opencode/commands/melt-{setup,plan,validate,review,pr,debug,audit,ux-audit,update,help}.md');
     }
     // Print summary
     console.log(chalk.green('Created files:'));
@@ -355,7 +371,7 @@ export async function initCommand(options) {
         console.log(chalk.cyan('Want support for your tool? Let us know in #dev on Slack'));
         console.log();
     }
-    const commandNames = 'melt-setup, melt-plan, melt-validate, melt-review, melt-pr, melt-debug, melt-audit, melt-update, melt-help';
+    const commandNames = 'melt-setup, melt-plan, melt-validate, melt-review, melt-pr, melt-debug, melt-audit, melt-ux-audit, melt-update, melt-help';
     if (tools.claude) {
         console.log(chalk.dim(`Available skills: /${commandNames.replace(/, /g, ', /')}`));
     }

package/dist/commands/report.d.ts

@@ -0,0 +1,7 @@
+export declare function reportPlanCommand(file?: string): Promise<void>;
+export declare function reportAuditCommand(file?: string): Promise<void>;
+export declare function reportListCommand(options: {
+    type?: string;
+    repository?: string;
+    limit?: string;
+}): Promise<void>;

package/dist/commands/report.js

@@ -0,0 +1,295 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+import { getStoredAuth, API_BASE } from '../utils/auth.js';
+async function getToken() {
+    const envToken = process.env['MELTCTL_TOKEN'];
+    if (envToken) {
+        return envToken;
+    }
+    const auth = await getStoredAuth();
+    if (!auth) {
+        console.error(chalk.red('Not authenticated. Run `npx @meltstudio/meltctl@latest login` or set MELTCTL_TOKEN for CI.'));
+        process.exit(1);
+    }
+    if (new Date(auth.expiresAt) <= new Date()) {
+        console.error(chalk.red('Session expired. Run `npx @meltstudio/meltctl@latest login` to re-authenticate, or set MELTCTL_TOKEN for CI.'));
+        process.exit(1);
+    }
+    return auth.token;
+}
+async function tokenFetch(token, urlPath, options = {}) {
+    const response = await fetch(`${API_BASE}${urlPath}`, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${token}`,
+            ...options.headers,
+        },
+    });
+    if (response.status === 401) {
+        throw new Error('Authentication failed. Run `npx @meltstudio/meltctl@latest login` or check your MELTCTL_TOKEN.');
+    }
+    return response;
+}
+function getGitBranch() {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function getGitCommit() {
+    try {
+        return execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function getGitRepository() {
+    try {
+        const url = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+        // Extract owner/repo from various URL formats:
+        // git@github.com:Owner/Repo.git -> Owner/Repo
+        // https://github.com/Owner/Repo.git -> Owner/Repo
+        // git@gitlab.com:Owner/Repo.git -> Owner/Repo
+        const match = url.match(/[/:]([\w.-]+\/[\w.-]+?)(?:\.git)?$/);
+        const slug = match ? match[1] : url;
+        return { slug, url };
+    }
+    catch {
+        return null;
+    }
+}
+function getProjectName() {
+    const cwd = process.cwd();
+    try {
+        const pkgPath = path.join(cwd, 'package.json');
+        if (fs.pathExistsSync(pkgPath)) {
+            const pkg = fs.readJsonSync(pkgPath);
+            if (pkg.name) {
+                return pkg.name;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return path.basename(cwd);
+}
+function extractTicketId(branch) {
+    const match = branch.match(/([A-Z]+-\d+)/i);
+    return match ? match[1] : null;
+}
+async function findMdFiles(dir) {
+    if (!(await fs.pathExists(dir))) {
+        return [];
+    }
+    const results = [];
+    async function walk(current) {
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                const stat = await fs.stat(fullPath);
+                results.push({ path: fullPath, mtime: stat.mtimeMs });
+            }
+        }
+    }
+    await walk(dir);
+    results.sort((a, b) => b.mtime - a.mtime);
+    return results.map(r => r.path);
+}
+async function autoDetectPlanFile() {
+    const cwd = process.cwd();
+    const plansDir = path.join(cwd, '.plans');
+    const mdFiles = await findMdFiles(plansDir);
+    if (mdFiles.length === 0) {
+        return null;
+    }
+    const branch = getGitBranch();
+    const ticketId = extractTicketId(branch);
+    if (ticketId) {
+        const ticketLower = ticketId.toLowerCase();
+        const match = mdFiles.find(f => path.basename(f).toLowerCase().includes(ticketLower));
+        if (match) {
+            return match;
+        }
+    }
+    return mdFiles[0] ?? null;
+}
+async function autoDetectAuditFile() {
+    const cwd = process.cwd();
+    // Check .audits/ directory first (most recent file)
+    const auditsDir = path.join(cwd, '.audits');
+    const auditFiles = await findMdFiles(auditsDir);
+    if (auditFiles.length > 0) {
+        return auditFiles[0] ?? null;
+    }
+    // Fall back to legacy locations
+    const candidates = ['AUDIT.md', 'UX-AUDIT.md'];
+    for (const name of candidates) {
+        const filePath = path.join(cwd, name);
+        if (await fs.pathExists(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+function buildReportPayload(type, content, filename) {
+    const project = getProjectName();
+    const branch = getGitBranch();
+    const commit = getGitCommit();
+    const repo = getGitRepository();
+    return {
+        type,
+        project,
+        repository: repo?.slug ?? null,
+        repositoryUrl: repo?.url ?? null,
+        branch,
+        commit,
+        content,
+        metadata: { filename },
+    };
+}
+export async function reportPlanCommand(file) {
+    const token = await getToken();
+    let filePath;
+    if (file) {
+        filePath = path.resolve(file);
+    }
+    else {
+        const detected = await autoDetectPlanFile();
+        if (!detected) {
+            console.error(chalk.red('No plan file found. Provide a file path or create a plan in the .plans/ directory.'));
+            process.exit(1);
+        }
+        filePath = detected;
+        console.log(chalk.dim(`Auto-detected plan file: ${path.relative(process.cwd(), filePath)}`));
+    }
+    if (!(await fs.pathExists(filePath))) {
+        console.error(chalk.red(`File not found: ${filePath}`));
+        process.exit(1);
+    }
+    const content = await fs.readFile(filePath, 'utf-8');
+    const filename = path.basename(filePath);
+    const payload = buildReportPayload('plan', content, filename);
+    try {
+        const res = await tokenFetch(token, '/reports', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            console.log(chalk.green(`\n  ✓ Plan report submitted! Report ID: ${body.id}\n`));
+        }
+        else {
+            const body = (await res.json());
+            console.error(chalk.red(`\nFailed to submit plan report: ${body.error ?? res.statusText}`));
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Failed to submit plan report: ${error instanceof Error ? error.message : 'Unknown error'}`));
+        process.exit(1);
+    }
+}
+export async function reportAuditCommand(file) {
+    const token = await getToken();
+    let filePath;
+    if (file) {
+        filePath = path.resolve(file);
+    }
+    else {
+        const detected = await autoDetectAuditFile();
+        if (!detected) {
+            console.error(chalk.red('No audit file found. Provide a file path or create AUDIT.md or UX-AUDIT.md in the project root.'));
+            process.exit(1);
+        }
+        filePath = detected;
+        console.log(chalk.dim(`Auto-detected audit file: ${path.relative(process.cwd(), filePath)}`));
+    }
+    if (!(await fs.pathExists(filePath))) {
+        console.error(chalk.red(`File not found: ${filePath}`));
+        process.exit(1);
+    }
+    const content = await fs.readFile(filePath, 'utf-8');
+    const filename = path.basename(filePath);
+    const payload = buildReportPayload('audit', content, filename);
+    try {
+        const res = await tokenFetch(token, '/reports', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            console.log(chalk.green(`\n  ✓ Audit report submitted! Report ID: ${body.id}\n`));
+        }
+        else {
+            const body = (await res.json());
+            console.error(chalk.red(`\nFailed to submit audit report: ${body.error ?? res.statusText}`));
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(`Failed to submit audit report: ${error instanceof Error ? error.message : 'Unknown error'}`));
+        process.exit(1);
+    }
+}
+export async function reportListCommand(options) {
+    const token = await getToken();
+    const params = new URLSearchParams();
+    if (options.type)
+        params.set('type', options.type);
+    if (options.repository)
+        params.set('repository', options.repository);
+    if (options.limit)
+        params.set('limit', options.limit);
+    const query = params.toString();
+    const urlPath = `/reports${query ? `?${query}` : ''}`;
+    try {
+        const res = await tokenFetch(token, urlPath);
+        if (res.status === 403) {
+            console.error(chalk.red('Access denied. Only Team Managers can list reports.'));
+            process.exit(1);
+        }
+        if (!res.ok) {
+            const body = (await res.json());
+            console.error(chalk.red(`Failed to list reports: ${body.error ?? res.statusText}`));
+            process.exit(1);
+        }
+        const body = (await res.json());
+        if (body.reports.length === 0) {
+            console.log(chalk.dim('\n  No reports found.\n'));
+            return;
+        }
+        console.log(chalk.bold(`\n  Reports (${body.count}):\n`));
+        for (const r of body.reports) {
+            const date = new Date(r.createdAt).toLocaleDateString('en-US', {
+                month: 'short',
+                day: 'numeric',
+                year: 'numeric',
+                hour: '2-digit',
+                minute: '2-digit',
+            });
+            const repo = r.repository ?? r.project;
+            const typeColor = r.type === 'plan' ? chalk.cyan : chalk.magenta;
+            console.log(`  ${typeColor(r.type.padEnd(6))} ${chalk.white(repo.padEnd(40))} ${chalk.dim(r.author.padEnd(30))} ${chalk.dim(date)}`);
+            if (r.branch && r.branch !== 'main') {
+                console.log(`         ${chalk.dim(`branch: ${r.branch}  commit: ${r.commit ?? 'N/A'}`)}`);
+            }
+        }
+        console.log();
+    }
+    catch (error) {
+        console.error(chalk.red(`Failed to list reports: ${error instanceof Error ? error.message : 'Unknown error'}`));
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -14,6 +14,7 @@ import { versionCheckCommand } from './commands/version.js';
 import { standupCommand } from './commands/standup.js';
 import { feedbackCommand } from './commands/feedback.js';
 import { coinsCommand } from './commands/coins.js';
+import { reportPlanCommand, reportAuditCommand, reportListCommand } from './commands/report.js';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -89,6 +90,30 @@ program
     .action(async (options) => {
     await coinsCommand(options);
 });
+const report = program.command('report').description('submit project reports (plans, audits)');
+report
+    .command('plan')
+    .description('submit a plan report from a markdown file')
+    .argument('[file]', 'path to the plan file (auto-detects from .plans/ if omitted)')
+    .action(async (file) => {
+    await reportPlanCommand(file);
+});
+report
+    .command('audit')
+    .description('submit an audit report from a markdown file')
+    .argument('[file]', 'path to the audit file (auto-detects AUDIT.md or UX-AUDIT.md if omitted)')
+    .action(async (file) => {
+    await reportAuditCommand(file);
+});
+report
+    .command('list')
+    .description('list submitted reports (Team Managers only)')
+    .option('--type <type>', 'filter by type (plan, audit)')
+    .option('--repository <repo>', 'filter by repository (owner/repo)')
+    .option('--limit <n>', 'max results (default 50, max 200)')
+    .action(async (options) => {
+    await reportListCommand(options);
+});
 program
     .command('version')
     .description('show current version')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meltstudio/meltctl",
-  "version": "4.23.1",
+  "version": "4.24.1",
   "description": "AI-first development tools for teams - set up AGENTS.md, Claude Code, Cursor, and OpenCode standards",
   "main": "dist/index.js",
   "type": "module",