@meltstudio/meltctl 2.4.0 → 3.0.0

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+interface InitOptions {
+    force?: boolean;
+}
+export declare function initCommand(options: InitOptions): Promise<void>;
+export {};

package/dist/commands/init.js

@@ -0,0 +1,102 @@
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, '../../templates');
+const SKILL_FRONTMATTER = {
+    plan: `---
+user-invocable: true
+description: Design an implementation approach before writing code
+---
+
+`,
+    review: `---
+user-invocable: true
+description: Review changes against project standards
+---
+
+`,
+    pr: `---
+user-invocable: true
+description: Create a well-structured pull request
+---
+
+`,
+    debug: `---
+user-invocable: true
+description: Systematically investigate and fix bugs
+---
+
+`,
+};
+const GITIGNORE_ENTRIES = ['.env.local', '.claude/settings.local.json'];
+export async function initCommand(options) {
+    const cwd = process.cwd();
+    // Check if already initialized (AGENTS.md exists)
+    if (!options.force && (await fs.pathExists(path.join(cwd, 'AGENTS.md')))) {
+        console.log(chalk.yellow('Project already has an AGENTS.md file. Use --force to overwrite.'));
+        process.exit(1);
+    }
+    console.log(chalk.bold('Initializing Melt development tools...'));
+    console.log();
+    // Copy AGENTS.md
+    await fs.copyFile(path.join(TEMPLATES_DIR, 'agents-md.md'), path.join(cwd, 'AGENTS.md'));
+    // Copy .claude/settings.json
+    await fs.ensureDir(path.join(cwd, '.claude'));
+    await fs.copyFile(path.join(TEMPLATES_DIR, 'claude-settings.json'), path.join(cwd, '.claude/settings.json'));
+    // Create Claude skills from workflow templates
+    const workflows = ['plan', 'review', 'pr', 'debug'];
+    for (const name of workflows) {
+        const skillDir = path.join(cwd, `.claude/skills/melt-${name}`);
+        await fs.ensureDir(skillDir);
+        const workflowContent = await fs.readFile(path.join(TEMPLATES_DIR, `workflows/${name}.md`), 'utf-8');
+        const skillContent = SKILL_FRONTMATTER[name] + workflowContent;
+        await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillContent, 'utf-8');
+    }
+    // Copy .cursor/rules/standards.mdc
+    await fs.ensureDir(path.join(cwd, '.cursor/rules'));
+    await fs.copyFile(path.join(TEMPLATES_DIR, 'cursor-rules.mdc'), path.join(cwd, '.cursor/rules/standards.mdc'));
+    // Copy Cursor commands from workflow templates
+    await fs.ensureDir(path.join(cwd, '.cursor/commands'));
+    for (const name of workflows) {
+        await fs.copyFile(path.join(TEMPLATES_DIR, `workflows/${name}.md`), path.join(cwd, `.cursor/commands/melt-${name}.md`));
+    }
+    // Copy .mcp.json
+    await fs.copyFile(path.join(TEMPLATES_DIR, 'mcp-configs/base.json'), path.join(cwd, '.mcp.json'));
+    // Copy .env.melt.example
+    await fs.copyFile(path.join(TEMPLATES_DIR, 'env-melt-example'), path.join(cwd, '.env.melt.example'));
+    // Update .gitignore
+    await updateGitignore(cwd);
+    // Print summary
+    console.log(chalk.green('Created files:'));
+    console.log(chalk.dim('  AGENTS.md'));
+    console.log(chalk.dim('  .claude/settings.json'));
+    console.log(chalk.dim('  .claude/skills/melt-{plan,review,pr,debug}/SKILL.md'));
+    console.log(chalk.dim('  .cursor/rules/standards.mdc'));
+    console.log(chalk.dim('  .cursor/commands/melt-{plan,review,pr,debug}.md'));
+    console.log(chalk.dim('  .mcp.json'));
+    console.log(chalk.dim('  .env.melt.example'));
+    console.log();
+    console.log(chalk.yellow('Next steps:'));
+    console.log(chalk.dim('  1. Edit AGENTS.md to describe your project and add team-specific standards'));
+    console.log(chalk.dim('  2. Copy .env.melt.example to .env.local and fill in credentials'));
+    console.log(chalk.dim('  3. Commit the generated files'));
+    console.log();
+    console.log(chalk.green('Done!'));
+}
+async function updateGitignore(cwd) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let content = '';
+    if (await fs.pathExists(gitignorePath)) {
+        content = await fs.readFile(gitignorePath, 'utf-8');
+    }
+    const missingEntries = GITIGNORE_ENTRIES.filter(entry => !content.includes(entry));
+    if (missingEntries.length > 0) {
+        const suffix = content.endsWith('\n') || content === '' ? '' : '\n';
+        const section = missingEntries.length > 0
+            ? `${suffix}\n# Melt - local settings\n${missingEntries.join('\n')}\n`
+            : '';
+        await fs.writeFile(gitignorePath, content + section, 'utf-8');
+    }
+}

package/dist/index.js

@@ -3,9 +3,7 @@ import { Command } from '@commander-js/extra-typings';
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { initCommand } from './commands/project/init.js';
-import { updateCommand } from './commands/project/update.js';
-import { cleanCommand } from './commands/project/clean.js';
+import { initCommand } from './commands/init.js';
 import { checkAndEnforceUpdate } from './utils/version-check.js';
 import { versionCheckCommand } from './commands/version.js';
 // Read version from package.json
@@ -15,39 +13,18 @@ const packageJson = JSON.parse(readFileSync(join(__dirname, '../package.json'),
 const program = new Command();
 program
     .name('meltctl')
-    .description('CLI tool for Melt development process automation')
+    .description('AI-first development tools for teams')
     .version(packageJson.version)
     .hook('preAction', async () => {
     await checkAndEnforceUpdate();
 });
-// Project management commands
-const projectCommand = program
-    .command('project')
-    .description('Project setup and management commands');
-projectCommand
+program
     .command('init')
     .description('Initialize project with Melt development tools')
-    .option('--shell <type>', 'specify shell type (sh|ps)', 'auto')
-    .action(options => {
-    // Validate shell option
-    const validShells = ['sh', 'ps', 'auto'];
-    const shell = validShells.includes(options.shell)
-        ? options.shell
-        : 'auto';
-    return initCommand({ shell });
-});
-projectCommand
-    .command('update')
-    .description('Update project configurations to latest version')
-    .action(updateCommand);
-projectCommand
-    .command('clean')
-    .description('Remove all Melt-generated files from the project')
-    .option('-y, --yes', 'skip confirmation prompt')
+    .option('--force', 'overwrite existing files')
     .action(options => {
-    return cleanCommand({ yes: options.yes });
+    return initCommand({ force: options.force });
 });
-// Version check command
 program
     .command('version')
     .description('Display version information')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meltstudio/meltctl",
-  "version": "2.4.0",
-  "description": "CLI tool for Melt development process automation - initialize and update project configurations",
+  "version": "3.0.0",
+  "description": "AI-first development tools for teams - set up AGENTS.md, Claude Code, Cursor, and Copilot standards",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -37,7 +37,10 @@
   "keywords": [
     "cli",
     "development-tools",
+    "agents-md",
+    "claude-code",
     "cursor",
+    "copilot",
     "ai-development",
     "melt",
     "automation"
@@ -45,11 +48,9 @@
   "author": "Melt Studio",
   "license": "MIT",
   "dependencies": {
-    "@clack/prompts": "^0.9.0",
     "commander": "^12.1.0",
     "@commander-js/extra-typings": "^12.1.0",
     "chalk": "^5.4.1",
-    "ora": "^8.2.0",
     "fs-extra": "^11.2.0"
   },
   "devDependencies": {

package/templates/agents-md.md

@@ -0,0 +1,117 @@
+# AGENTS.md
+
+## Project Overview
+
+<!-- Describe your project here: what it does, key technologies, and architecture overview -->
+
+## Architecture Standards
+
+### Important: Respect Existing Code
+
+Before applying any standards below, **understand the existing project structure first**. If the project already follows a different architecture or pattern, continue following the existing conventions. These standards apply to new code in greenfield areas - never refactor or restructure existing code to match these guidelines unless explicitly asked.
+
+### Recommended Structure (for new projects/domains)
+
+For new frontend code, prefer domain-driven architecture:
+
+```
+src/
+  domains/
+    <domain>/
+      components/     # UI components scoped to this domain
+      hooks/          # Custom hooks for this domain
+      services/       # API calls and business logic
+      types/          # TypeScript types and interfaces
+      utils/          # Domain-specific utilities
+  shared/
+    components/       # Shared UI components
+    hooks/            # Shared custom hooks
+    services/         # Shared API services
+    types/            # Shared TypeScript types
+    utils/            # Shared utilities
+```
+
+- Each domain is self-contained with its own components, hooks, services, types, and utils
+- Cross-domain imports go through the `shared/` directory
+- Never import directly between domains
+
+If the project uses a different structure, follow the existing patterns instead.
+
+### TypeScript Standards
+- Strict mode enabled (`strict: true` in tsconfig)
+- No `any` types - use `unknown` with type guards when the type is truly unknown
+- Validate external data with Zod schemas at system boundaries
+- Export types from dedicated `types.ts` files
+
+### Code Quality
+- Minimum 80% test coverage for new code
+- Use conventional commits (feat:, fix:, chore:, docs:, refactor:, test:)
+- No eslint-disable comments without team approval
+- All functions must have explicit return types
+- Prefer composition over inheritance
+
+## Agent Permissions
+
+### Automatically Approved (No Confirmation Needed)
+- Reading any file in the repository
+- Running tests, linters, type checkers, and formatters
+- Git read operations (status, log, diff, branch)
+- Searching code and exploring the codebase
+- Package dependency lookups
+
+### Requires Approval
+- Writing or modifying files
+- Git write operations (add, commit, checkout, branch creation)
+- Running build commands
+- Installing or removing dependencies
+- Creating pull requests or issues
+
+### Blocked (Never Execute)
+- `git push --force` or `git push --force-with-lease`
+- `git reset --hard`
+- `rm -rf /` or any recursive delete of root paths
+- Force push to main or master branches
+- Dropping database tables in production
+- Modifying CI/CD pipeline files without explicit request
+
+## Tool Access
+
+### CLI Tools
+- Use `gh` CLI for GitHub operations (PRs, issues, releases)
+- Use project's package manager (check for yarn.lock, pnpm-lock.yaml, or package-lock.json)
+- Run tests with the project's configured test runner
+
+### Browser (via DevTools MCP)
+- Use Chrome DevTools MCP server for browser testing when available
+- Inspect elements, check console errors, verify visual output
+- Test responsive layouts and interactions
+
+### Databases
+- Read queries are safe to execute
+- Write queries require approval
+- Schema changes require explicit request and approval
+
+## Project Management
+
+- Reference issue/ticket IDs in commit messages and PR descriptions
+- Follow the team's workflow for issue progression
+- Update ticket status when starting and completing work
+
+## Workflow Skills
+
+The following workflows are available as AI skills:
+
+- **plan** - Gather requirements, explore codebase, design approach, present plan for approval
+- **review** - Review changes against these standards, categorize findings
+- **pr** - Analyze changes, draft PR description, run pre-flight checks, create PR
+- **debug** - Investigate issues, isolate root cause, write regression test, fix
+
+## Customization
+
+<!-- Add project-specific standards below this line -->
+<!-- Examples of things to add: -->
+<!-- - API conventions (REST patterns, error formats, pagination) -->
+<!-- - Component patterns (naming, file structure, state management) -->
+<!-- - Database rules (naming conventions, migration patterns) -->
+<!-- - Testing patterns (what to mock, integration test setup) -->
+<!-- - Deployment rules (environment-specific concerns) -->

package/templates/claude-settings.json

@@ -0,0 +1,36 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git status*)",
+      "Bash(git log*)",
+      "Bash(git diff*)",
+      "Bash(git branch*)",
+      "Bash(git show*)",
+      "Bash(npm test*)",
+      "Bash(yarn test*)",
+      "Bash(pnpm test*)",
+      "Bash(npx vitest*)",
+      "Bash(npx jest*)",
+      "Bash(npm run lint*)",
+      "Bash(yarn lint*)",
+      "Bash(pnpm lint*)",
+      "Bash(npm run build*)",
+      "Bash(yarn build*)",
+      "Bash(pnpm build*)",
+      "Bash(npx tsc*)",
+      "Bash(gh pr *)",
+      "Bash(gh issue *)",
+      "Read(*)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(git push * --force*)",
+      "Bash(git push --force-with-lease*)",
+      "Bash(git push * --force-with-lease*)",
+      "Bash(git reset --hard*)",
+      "Bash(rm -rf /*)",
+      "Bash(git push * main*)",
+      "Bash(git push * master*)"
+    ]
+  }
+}

package/templates/cursor-rules.mdc

@@ -0,0 +1,39 @@
+---
+description: Melt development standards and architecture guidelines
+globs:
+alwaysApply: true
+---
+
+# Project Standards
+
+## Important
+- Always understand the existing project structure before making changes
+- If the project follows different conventions than listed here, follow the existing patterns
+- These standards apply to new greenfield code - never refactor existing code to match unless asked
+
+## Architecture
+- Prefer domain-driven architecture for new code: `src/domains/<domain>/{components,hooks,services,types,utils}`
+- Cross-domain imports go through `src/shared/`
+- Never import directly between domains
+- Follow existing project patterns when they differ from the above
+
+## TypeScript
+- Strict mode enabled, no `any` types
+- Validate external data with Zod at system boundaries
+- All functions must have explicit return types
+
+## Code Quality
+- 80% minimum test coverage for new code
+- Conventional commits (feat:, fix:, chore:, docs:, refactor:, test:)
+- No eslint-disable comments without team approval
+
+## Agent Behavior
+- Read operations: auto-approved
+- Write operations: require developer approval
+- Destructive operations: blocked (no force push, no hard reset)
+
+## Workflows
+- Use `plan` before starting non-trivial implementations
+- Use `review` to check changes against these standards
+- Use `pr` to create well-structured pull requests
+- Use `debug` for systematic bug investigation

package/templates/env-melt-example

@@ -0,0 +1,23 @@
+# Melt Development Tools - Environment Variables
+# Copy this file to .env.local and fill in your values
+# Never commit .env.local to version control
+
+# --- Linear (if using Linear for project management) ---
+# LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# --- Jira (if using Jira for project management) ---
+# JIRA_API_TOKEN=your-jira-api-token
+# JIRA_BASE_URL=https://your-org.atlassian.net
+# JIRA_USER_EMAIL=your-email@company.com
+
+# --- Database (if agents need database access) ---
+# DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# --- AWS (if agents need AWS access) ---
+# AWS_ACCESS_KEY_ID=your-access-key
+# AWS_SECRET_ACCESS_KEY=your-secret-key
+# AWS_REGION=us-east-1
+
+# --- Other Integrations ---
+# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+# ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

package/templates/mcp-configs/base.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/chrome-devtools-mcp@latest"]
+    }
+  }
+}

package/templates/workflows/debug.md

@@ -0,0 +1,32 @@
+# Debug
+
+Investigate and fix bugs systematically.
+
+## Instructions
+
+1. **Understand the Problem**
+   - Read the bug report or error description
+   - Reproduce the issue if possible
+   - Identify expected vs actual behavior
+
+2. **Investigate**
+   - Search the codebase for relevant code paths
+   - Read error messages and stack traces carefully
+   - Use browser DevTools MCP if it's a UI issue
+   - Check recent changes that might have introduced the bug
+   - Add temporary logging if needed to trace execution
+
+3. **Isolate the Root Cause**
+   - Narrow down to the specific file and function
+   - Understand why the current code produces the wrong behavior
+   - Verify your hypothesis by checking related code paths
+
+4. **Write a Regression Test**
+   - Write a test that reproduces the bug (it should fail before the fix)
+   - Cover the specific edge case that caused the issue
+
+5. **Fix the Bug**
+   - Make the minimal change needed to fix the issue
+   - Verify the regression test now passes
+   - Run the full test suite to check for regressions
+   - Clean up any temporary debugging code

package/templates/workflows/plan.md

@@ -0,0 +1,32 @@
+# Plan
+
+Design an implementation approach before writing code.
+
+## Instructions
+
+1. **Gather Requirements**
+   - Read the task description carefully
+   - Identify acceptance criteria and constraints
+   - Ask clarifying questions if requirements are ambiguous
+
+2. **Explore the Codebase**
+   - Find relevant files and understand existing patterns
+   - Check for similar implementations to follow as examples
+   - Identify files that will need changes
+
+3. **Design the Approach**
+   - Break the task into concrete implementation steps
+   - Consider edge cases and error handling
+   - Note any dependencies or ordering constraints
+   - Estimate which files will be created or modified
+
+4. **Present the Plan**
+   - Summarize the approach in a clear, numbered list
+   - Highlight any architectural decisions or trade-offs
+   - List files to be modified with a brief description of changes
+   - Call out any risks or open questions
+
+5. **Wait for Approval**
+   - Do not start implementation until the developer approves
+   - Adjust the plan based on feedback
+   - Once approved, proceed with implementation

package/templates/workflows/pr.md

@@ -0,0 +1,28 @@
+# Pull Request
+
+Create a well-structured pull request from the current changes.
+
+## Instructions
+
+1. **Analyze Changes**
+   - Run `git diff` to understand all changes
+   - Run `git log` to review commit history on this branch
+   - Identify the purpose and scope of the changes
+
+2. **Draft PR Description**
+   - Write a clear title (under 70 characters)
+   - Summarize changes in 1-3 bullet points
+   - Reference related issues or tickets
+   - Note any breaking changes or migration steps
+
+3. **Run Pre-flight Checks**
+   - Run the test suite and verify all tests pass
+   - Run the linter and fix any issues
+   - Run type checking and resolve any errors
+   - Verify the build succeeds
+
+4. **Create the PR**
+   - Use `gh pr create` with the drafted title and description
+   - Add appropriate labels if the project uses them
+   - Request reviewers if specified
+   - Return the PR URL to the developer

package/templates/workflows/review.md

@@ -0,0 +1,28 @@
+# Review
+
+Review code changes against project standards.
+
+## Instructions
+
+1. **Understand Context**
+   - Read the PR description or task context
+   - Understand what the changes are trying to accomplish
+   - Check AGENTS.md for project-specific standards
+
+2. **Review the Changes**
+   - Read all modified files carefully
+   - Check for correctness, readability, and maintainability
+   - Verify adherence to architecture standards (domain structure, typing, etc.)
+   - Look for potential bugs, edge cases, or security issues
+   - Check that tests cover the changes adequately
+
+3. **Categorize Findings**
+   - **Must Fix**: Bugs, security issues, broken functionality, standards violations
+   - **Should Fix**: Code quality issues, missing tests, unclear naming
+   - **Suggestion**: Style preferences, optional improvements, alternative approaches
+
+4. **Present the Review**
+   - Start with a summary of what the changes do
+   - List findings by category with file paths and line numbers
+   - Provide specific suggestions for how to fix each issue
+   - End with an overall assessment (approve, request changes, or needs discussion)

package/dist/commands/project/clean.d.ts

@@ -1,5 +0,0 @@
-interface CleanOptions {
-    yes?: boolean;
-}
-export declare function cleanCommand(options?: CleanOptions): Promise<void>;
-export {};