clavix 2.7.0 → 2.8.0

package/README.md

@@ -26,6 +26,8 @@ Provider paths and argument placeholders are listed in [docs/providers.md](docs/
 
 ## Quickstart
 
+> **⚠️ v2.8.0 Breaking Change**: Clavix is now a pure ESM package. Requires **Node.js ≥ 16.0.0**. See [CHANGELOG.md](CHANGELOG.md#280---2025-11-17) for migration details.
+
 ### For AI Agents (Recommended)
 
 Most Clavix users work through AI coding assistants:
@@ -94,21 +96,33 @@ clavix prd
 - CLEAR Framework: [docs/clear-framework.md](docs/clear-framework.md)
 - Guides: [docs/guides/](docs/guides/workflows.md)
 
-## Development
-- Requires Node.js ≥ 18
-- Run tests: `npm test`
+## Requirements
+
+### For End Users
+- **Node.js ≥ 16.0.0** (required for ESM support)
+- npm or yarn package manager
+
+### For Contributors
+- **Node.js ≥ 16.0.0** (pure ESM package since v2.8.0)
+- Run tests: `npm test` (uses `--experimental-vm-modules` for Jest with ESM)
 - Lint: `npm run lint`
-- Build: `npm run build`
+- Build: `npm run build` (TypeScript ES2020 modules)
+
+**ESM Migration (v2.8.0+):**
+- All source code uses ES modules (`import`/`export`)
+- TypeScript configured with `NodeNext` module resolution
+- All imports require `.js` file extensions
+- See [ESM_MIGRATION_NOTES.md](ESM_MIGRATION_NOTES.md) for details
 
 ## License
 MIT
 
 ## Star History
 
-<a href="https://www.star-history.com/#Bob5k/Clavix&type=date&legend=top-left">
+<a href="https://www.star-history.com/#ClavixDev/Clavix&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Bob5k/Clavix&type=date&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Bob5k/Clavix&type=date&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Bob5k/Clavix&type=date&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
  </picture>
 </a>

package/bin/clavix.js

@@ -1,8 +1,17 @@
 #!/usr/bin/env node
 
-// Disable debug mode (stack traces) unless explicitly requested via DEBUG env var
+import { run, handle, settings } from '@oclif/core';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Get the project root (one level up from bin/)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, '..');
+
+// Disable debug mode unless explicitly requested
 if (!process.env.DEBUG) {
-  require('@oclif/core').settings.debug = false;
+  settings.debug = false;
 }
 
 // Custom error handler to suppress stack traces
@@ -15,10 +24,8 @@ async function handleError(error) {
   }
 
   // For other errors, use default handler
-  const { handle } = require('@oclif/core');
   return handle(error);
 }
 
-require('../dist/index.js')
-  .run()
+run(undefined, projectRoot)
   .catch(handleError);

package/dist/cli/commands/archive.d.ts

@@ -3,12 +3,13 @@ export default class Archive extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        project: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        project: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
-        list: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        force: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        restore: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        restore: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     /**

package/dist/cli/commands/archive.js

@@ -1,53 +1,50 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
+import { Command, Flags, Args } from '@oclif/core';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { ArchiveManager } from '../../core/archive-manager.js';
+export default class Archive extends Command {
+    static description = 'Archive completed PRD projects';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> # Interactive selection',
+        '<%= config.bin %> <%= command.id %> my-project # Archive specific project',
+        '<%= config.bin %> <%= command.id %> --list # List archived projects',
+        '<%= config.bin %> <%= command.id %> my-project --force # Force archive',
+        '<%= config.bin %> <%= command.id %> --restore my-project # Restore from archive',
+    ];
+    static args = {
+        project: Args.string({
+            description: 'Name of the project to archive',
+            required: false,
+        }),
     };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
+    static flags = {
+        list: Flags.boolean({
+            char: 'l',
+            description: 'List archived projects',
+            default: false,
+        }),
+        force: Flags.boolean({
+            char: 'f',
+            description: 'Force archive even if tasks are incomplete',
+            default: false,
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Skip all confirmation prompts (agent-friendly)',
+            default: false,
+        }),
+        restore: Flags.string({
+            char: 'r',
+            description: 'Restore an archived project',
+        }),
     };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const core_1 = require("@oclif/core");
-const chalk_1 = __importDefault(require("chalk"));
-const inquirer_1 = __importDefault(require("inquirer"));
-const archive_manager_1 = require("../../core/archive-manager");
-class Archive extends core_1.Command {
     async run() {
         const { args, flags } = await this.parse(Archive);
-        const archiveManager = new archive_manager_1.ArchiveManager();
+        const archiveManager = new ArchiveManager();
         try {
             // Handle restore flag
             if (flags.restore) {
-                await this.restoreProject(flags.restore, archiveManager);
+                await this.restoreProject(flags.restore, archiveManager, flags.yes);
                 return;
             }
             // Handle list flag
@@ -57,45 +54,45 @@ class Archive extends core_1.Command {
             }
             // Handle direct project archival
             if (args.project) {
-                await this.archiveSpecificProject(args.project, flags.force, archiveManager);
+                await this.archiveSpecificProject(args.project, flags.force, flags.yes, archiveManager);
                 return;
             }
             // Interactive mode
-            await this.interactiveArchive(archiveManager);
+            await this.interactiveArchive(archiveManager, flags.yes);
         }
         catch (error) {
-            const { getErrorMessage } = await Promise.resolve().then(() => __importStar(require('../../utils/error-utils.js')));
-            this.error(chalk_1.default.red(`Archive failed: ${getErrorMessage(error)}`));
+            const { getErrorMessage } = await import('../../utils/error-utils.js');
+            this.error(chalk.red(`Archive failed: ${getErrorMessage(error)}`));
         }
     }
     /**
      * Interactive archive mode - show list of archivable projects
      */
-    async interactiveArchive(archiveManager) {
-        this.log(chalk_1.default.bold.cyan('\n📦 Archive PRD Projects\n'));
+    async interactiveArchive(archiveManager, yes) {
+        this.log(chalk.bold.cyan('\n📦 Archive PRD Projects\n'));
         // Get all archivable projects (100% tasks completed)
         const archivableProjects = await archiveManager.getArchivablePrds();
         if (archivableProjects.length === 0) {
-            this.log(chalk_1.default.gray('No projects ready to archive.'));
-            this.log(chalk_1.default.gray('\nProjects can be archived when all tasks are completed.'));
-            this.log(chalk_1.default.gray('Use ') + chalk_1.default.cyan('clavix list --outputs') + chalk_1.default.gray(' to see all projects.'));
+            this.log(chalk.gray('No projects ready to archive.'));
+            this.log(chalk.gray('\nProjects can be archived when all tasks are completed.'));
+            this.log(chalk.gray('Use ') + chalk.cyan('clavix list --outputs') + chalk.gray(' to see all projects.'));
             return;
         }
         // Show archivable projects
-        this.log(chalk_1.default.green(`Found ${archivableProjects.length} project(s) ready to archive:\n`));
+        this.log(chalk.green(`Found ${archivableProjects.length} project(s) ready to archive:\n`));
         // Inquirer choices can be mixed types (choices + separators)
         const choices = archivableProjects.map((project) => ({
             name: `${project.name} (${project.taskStatus.completed} tasks completed)`,
             value: project.name,
             short: project.name,
         }));
-        choices.push(new inquirer_1.default.Separator());
+        choices.push(new inquirer.Separator());
         choices.push({
-            name: chalk_1.default.gray('Cancel'),
+            name: chalk.gray('Cancel'),
             value: '__cancel__',
             short: 'Cancel',
         });
-        const { selectedProject } = await inquirer_1.default.prompt([
+        const { selectedProject } = await inquirer.prompt([
             {
                 type: 'list',
                 name: 'selectedProject',
@@ -105,101 +102,107 @@ class Archive extends core_1.Command {
             },
         ]);
         if (selectedProject === '__cancel__') {
-            this.log(chalk_1.default.yellow('\n✗ Archive cancelled\n'));
+            this.log(chalk.yellow('\n✗ Archive cancelled\n'));
             return;
         }
-        // Confirm archival
-        const { confirm } = await inquirer_1.default.prompt([
-            {
-                type: 'confirm',
-                name: 'confirm',
-                message: `Archive "${selectedProject}"? (This will move it to .clavix/outputs/archive/)`,
-                default: false,
-            },
-        ]);
-        if (!confirm) {
-            this.log(chalk_1.default.yellow('\n✗ Archive cancelled\n'));
-            return;
+        // Confirm archival (unless --yes)
+        if (!yes) {
+            const { confirm } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'confirm',
+                    message: `Archive "${selectedProject}"? (This will move it to .clavix/outputs/archive/)`,
+                    default: false,
+                },
+            ]);
+            if (!confirm) {
+                this.log(chalk.yellow('\n✗ Archive cancelled\n'));
+                return;
+            }
         }
         // Archive the project
         const result = await archiveManager.archiveProject(selectedProject);
         if (result.success) {
-            this.log(chalk_1.default.green(`\n✓ ${result.message}\n`));
+            this.log(chalk.green(`\n✓ ${result.message}\n`));
         }
         else {
-            this.error(chalk_1.default.red(`\n✗ ${result.message}\n`));
+            this.error(chalk.red(`\n✗ ${result.message}\n`));
         }
     }
     /**
      * Archive a specific project by name
      */
-    async archiveSpecificProject(projectName, force, archiveManager) {
-        this.log(chalk_1.default.cyan(`\nArchiving project: ${chalk_1.default.bold(projectName)}\n`));
+    async archiveSpecificProject(projectName, force, yes, archiveManager) {
+        this.log(chalk.cyan(`\nArchiving project: ${chalk.bold(projectName)}\n`));
         // Check task status
         const projectPath = `.clavix/outputs/${projectName}`;
         const taskStatus = await archiveManager.checkTasksStatus(projectPath);
-        // If not forcing and tasks are incomplete, ask for confirmation
+        // If not forcing and tasks are incomplete, ask for confirmation (unless --yes)
         if (!force && !taskStatus.allCompleted) {
             if (!taskStatus.hasTasksFile) {
-                this.log(chalk_1.default.yellow(`⚠ Project has no tasks.md file\n`));
-                const { proceed } = await inquirer_1.default.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'proceed',
-                        message: 'Archive anyway?',
-                        default: false,
-                    },
-                ]);
-                if (!proceed) {
-                    this.log(chalk_1.default.yellow('\n✗ Archive cancelled\n'));
-                    return;
+                this.log(chalk.yellow(`⚠ Project has no tasks.md file\n`));
+                if (!yes) {
+                    const { proceed } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'proceed',
+                            message: 'Archive anyway?',
+                            default: false,
+                        },
+                    ]);
+                    if (!proceed) {
+                        this.log(chalk.yellow('\n✗ Archive cancelled\n'));
+                        return;
+                    }
                 }
             }
             else if (taskStatus.remaining > 0) {
-                this.log(chalk_1.default.yellow(`⚠ Project has ${taskStatus.remaining} incomplete task(s):\n`));
+                this.log(chalk.yellow(`⚠ Project has ${taskStatus.remaining} incomplete task(s):\n`));
                 // Show incomplete tasks
                 const incompleteTasks = await archiveManager.getIncompleteTasks(projectPath);
                 incompleteTasks.slice(0, 5).forEach((task) => {
-                    this.log(chalk_1.default.gray(`  • ${task}`));
+                    this.log(chalk.gray(`  • ${task}`));
                 });
                 if (incompleteTasks.length > 5) {
-                    this.log(chalk_1.default.gray(`  ... and ${incompleteTasks.length - 5} more\n`));
+                    this.log(chalk.gray(`  ... and ${incompleteTasks.length - 5} more\n`));
                 }
                 else {
                     this.log('');
                 }
-                const { proceed } = await inquirer_1.default.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'proceed',
-                        message: 'Archive anyway?',
-                        default: false,
-                    },
-                ]);
-                if (!proceed) {
-                    this.log(chalk_1.default.yellow('\n✗ Archive cancelled\n'));
-                    return;
+                if (!yes) {
+                    const { proceed } = await inquirer.prompt([
+                        {
+                            type: 'confirm',
+                            name: 'proceed',
+                            message: 'Archive anyway?',
+                            default: false,
+                        },
+                    ]);
+                    if (!proceed) {
+                        this.log(chalk.yellow('\n✗ Archive cancelled\n'));
+                        return;
+                    }
                 }
             }
         }
         // Archive the project
         const result = await archiveManager.archiveProject(projectName, true);
         if (result.success) {
-            this.log(chalk_1.default.green(`✓ ${result.message}\n`));
+            this.log(chalk.green(`✓ ${result.message}\n`));
         }
         else {
-            this.error(chalk_1.default.red(`✗ ${result.message}\n`));
+            this.error(chalk.red(`✗ ${result.message}\n`));
         }
     }
     /**
      * List all archived projects
      */
     async listArchivedProjects(archiveManager) {
-        this.log(chalk_1.default.bold.cyan('\n📦 Archived Projects\n'));
+        this.log(chalk.bold.cyan('\n📦 Archived Projects\n'));
         const archivedProjects = await archiveManager.listArchivedProjects();
         if (archivedProjects.length === 0) {
-            this.log(chalk_1.default.gray('No archived projects found.'));
-            this.log(chalk_1.default.gray('\nUse ') + chalk_1.default.cyan('clavix archive') + chalk_1.default.gray(' to archive completed projects.\n'));
+            this.log(chalk.gray('No archived projects found.'));
+            this.log(chalk.gray('\nUse ') + chalk.cyan('clavix archive') + chalk.gray(' to archive completed projects.\n'));
             return;
         }
         // Display archived projects
@@ -209,40 +212,42 @@ class Archive extends core_1.Command {
                 ? `${project.taskStatus.completed}/${project.taskStatus.total} tasks`
                 : 'no tasks';
             const modified = project.modifiedTime.toLocaleDateString();
-            this.log(`  ${statusIcon} ${chalk_1.default.bold(project.name)}` +
-                `\n     ${chalk_1.default.gray('Tasks:')} ${taskInfo} ${chalk_1.default.gray('│')} ` +
-                `${chalk_1.default.gray('Archived:')} ${modified}` +
-                `\n     ${chalk_1.default.gray('Path:')} ${chalk_1.default.dim(project.path)}` +
+            this.log(`  ${statusIcon} ${chalk.bold(project.name)}` +
+                `\n     ${chalk.gray('Tasks:')} ${taskInfo} ${chalk.gray('│')} ` +
+                `${chalk.gray('Archived:')} ${modified}` +
+                `\n     ${chalk.gray('Path:')} ${chalk.dim(project.path)}` +
                 (index < archivedProjects.length - 1 ? '\n' : ''));
         });
         this.log('');
-        this.log(chalk_1.default.gray(`  Total: ${archivedProjects.length} archived project(s)`));
-        this.log(chalk_1.default.gray(`  Use ${chalk_1.default.cyan('clavix archive --restore <project>')} to restore a project\n`));
+        this.log(chalk.gray(`  Total: ${archivedProjects.length} archived project(s)`));
+        this.log(chalk.gray(`  Use ${chalk.cyan('clavix archive --restore <project>')} to restore a project\n`));
     }
     /**
      * Restore an archived project
      */
-    async restoreProject(projectName, archiveManager) {
-        this.log(chalk_1.default.cyan(`\nRestoring project: ${chalk_1.default.bold(projectName)}\n`));
-        // Confirm restoration
-        const { confirm } = await inquirer_1.default.prompt([
-            {
-                type: 'confirm',
-                name: 'confirm',
-                message: `Restore "${projectName}" from archive?`,
-                default: false,
-            },
-        ]);
-        if (!confirm) {
-            this.log(chalk_1.default.yellow('\n✗ Restore cancelled\n'));
-            return;
+    async restoreProject(projectName, archiveManager, yes) {
+        this.log(chalk.cyan(`\nRestoring project: ${chalk.bold(projectName)}\n`));
+        // Confirm restoration (unless --yes)
+        if (!yes) {
+            const { confirm } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'confirm',
+                    message: `Restore "${projectName}" from archive?`,
+                    default: false,
+                },
+            ]);
+            if (!confirm) {
+                this.log(chalk.yellow('\n✗ Restore cancelled\n'));
+                return;
+            }
         }
         const result = await archiveManager.restoreProject(projectName);
         if (result.success) {
-            this.log(chalk_1.default.green(`✓ ${result.message}\n`));
+            this.log(chalk.green(`✓ ${result.message}\n`));
         }
         else {
-            this.error(chalk_1.default.red(`✗ ${result.message}\n`));
+            this.error(chalk.red(`✗ ${result.message}\n`));
         }
     }
     /**
@@ -253,40 +258,9 @@ class Archive extends core_1.Command {
         const taskInfo = project.taskStatus.hasTasksFile
             ? `${project.taskStatus.completed}/${project.taskStatus.total} tasks (${Math.round(project.taskStatus.percentage)}%)`
             : 'no tasks';
-        this.log(`  ${statusIcon} ${chalk_1.default.bold(project.name)}` +
-            `\n     ${chalk_1.default.gray('Tasks:')} ${taskInfo}` +
-            `\n     ${chalk_1.default.gray('Modified:')} ${project.modifiedTime.toLocaleDateString()}`);
+        this.log(`  ${statusIcon} ${chalk.bold(project.name)}` +
+            `\n     ${chalk.gray('Tasks:')} ${taskInfo}` +
+            `\n     ${chalk.gray('Modified:')} ${project.modifiedTime.toLocaleDateString()}`);
     }
 }
-Archive.description = 'Archive completed PRD projects';
-Archive.examples = [
-    '<%= config.bin %> <%= command.id %> # Interactive selection',
-    '<%= config.bin %> <%= command.id %> my-project # Archive specific project',
-    '<%= config.bin %> <%= command.id %> --list # List archived projects',
-    '<%= config.bin %> <%= command.id %> my-project --force # Force archive',
-    '<%= config.bin %> <%= command.id %> --restore my-project # Restore from archive',
-];
-Archive.args = {
-    project: core_1.Args.string({
-        description: 'Name of the project to archive',
-        required: false,
-    }),
-};
-Archive.flags = {
-    list: core_1.Flags.boolean({
-        char: 'l',
-        description: 'List archived projects',
-        default: false,
-    }),
-    force: core_1.Flags.boolean({
-        char: 'f',
-        description: 'Force archive even if tasks are incomplete',
-        default: false,
-    }),
-    restore: core_1.Flags.string({
-        char: 'r',
-        description: 'Restore an archived project',
-    }),
-};
-exports.default = Archive;
 //# sourceMappingURL=archive.js.map

package/dist/cli/commands/config.d.ts

@@ -3,12 +3,12 @@ export default class Config extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        action: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
-        key: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
-        value: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        action: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        key: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        value: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
-        global: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        global: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
     private showInteractiveMenu;