ph-cmd 0.43.14-dev.0 → 0.43.14-dev.10

package/dist/src/help.js

@@ -0,0 +1,186 @@
+/**
+ * Help text for CLI commands
+ * This file centralizes all help text to keep command files clean
+ */
+/**
+ * Help text for the update command
+ */
+export const updateHelp = `
+Command Overview:
+  The update command helps you manage and update Powerhouse dependencies in your project. It provides
+  an efficient way to keep your project up-to-date with the latest versions of Powerhouse packages.
+  
+  This command:
+  1. Updates all Powerhouse dependencies based on the semver ranges specified in your package.json
+  2. Can force update all dependencies to a specific environment version (dev, prod, latest)
+  3. Automatically builds any local dependencies before updating
+  4. Works with all dependencies with @powerhousedao/ prefix and special packages like document-model
+
+Options:
+  --force <env>         Force update to the latest available version for the environment specified.
+                        Valid environments: dev, prod, latest.
+                        - dev: Uses @dev tag for all dependencies
+                        - prod/latest: Uses @latest tag for all dependencies
+                        
+  --package-manager     Override the auto-detected package manager with the specified one.
+                        
+  --debug               Show additional logs while executing the command.
+
+Special Cases:
+  - Local Dependencies: If you have dependencies linked from a local monorepo (using file: or link:
+    protocols), the command will detect the monorepo root, build affected packages, then update.
+  
+  - No Dependencies: If no Powerhouse dependencies are found in your project, the command will
+    display a message and exit without making changes.
+
+Examples:
+  $ ph update                          # Update dependencies based on package.json ranges
+  $ ph update --force dev              # Force update to latest dev version available
+  $ ph update --force prod             # Force update to latest stable version available (same as latest)
+  $ ph update --force latest           # Force update to latest stable version available (same as prod)
+  $ ph update --package-manager pnpm   # Specify package manager to use
+  $ ph update --debug                  # Show debug information during update
+`;
+/**
+ * Help text for the use command
+ */
+export const useHelp = `
+Command Overview:
+  The use command allows you to quickly switch between different environments for all Powerhouse
+  dependencies in your project. It provides a convenient way to toggle between development,
+  production, and local versions of the packages.
+
+  This command:
+  1. Updates all installed Powerhouse dependencies to the specified environment
+  2. Can link to local dependencies from a monorepo for development
+  3. Only updates dependencies that are already present in your package.json
+  4. Supports special packages without the @powerhousedao prefix
+
+Arguments:
+  <environment>         Required. The environment to use. Valid options:
+                        - dev: Use development versions (@dev tag)
+                        - prod/latest: Use production versions (@latest tag)
+                        - local: Use local filesystem versions (requires localPath)
+                        
+  [localPath]           Path to the local monorepo. Required when environment is 'local'.
+                        This should be the root of your Powerhouse monorepo.
+
+Options:
+  --force               Force environment to use, even if not in the predefined list
+                        
+  --package-manager     Override the auto-detected package manager with the specified one.
+                        
+  --debug               Show additional logs during execution for troubleshooting.
+
+Special Cases:
+  - Local Development: When using the 'local' environment, dependencies are linked directly
+    to local filesystem paths, allowing for real-time development and testing.
+  
+  - Missing Dependencies: The command only updates Powerhouse dependencies that are already
+    installed in your project. It won't add new ones.
+
+Examples:
+  $ ph use dev                       # Switch all dependencies to development versions
+  $ ph use prod                      # Switch all dependencies to production versions
+  $ ph use latest                    # Same as 'prod', use latest production versions
+  $ ph use local /path/to/monorepo   # Link to local versions in the specified monorepo
+  $ ph use dev --package-manager npm # Use npm instead of the auto-detected package manager
+  $ ph use dev --debug               # Show debug information during execution
+`;
+/**
+ * Help text for the setup-globals command
+ */
+export const setupGlobalsHelp = `
+Command Overview:
+  The setup-globals command initializes a new Powerhouse project with the necessary global 
+  configuration. It helps you set up a project quickly with proper defaults and dependencies.
+
+  This command:
+  1. Creates a new project with the specified name or in the current directory
+  2. Sets up all required Powerhouse dependencies
+  3. Configures the project with appropriate settings
+  4. Can run in interactive mode to guide you through the setup process
+
+Arguments:
+  [project-name]        Optional. Name of the project to create. If not provided,
+                        the command will use the current directory.
+
+Options:
+  -p, --project         Specify the name of the project to create.
+                        
+  -i, --interactive     Run the command in interactive mode, which will guide you
+                        through the setup process with questions and prompts.
+                        
+  -v, --version         Specify the development version to use. Defaults to "main".
+                        
+  --dev                 Use the "development" version of the boilerplate.
+                        
+  --staging             Use the "staging" version of the boilerplate.
+                        
+  --package-manager     Override the auto-detected package manager with the specified one.
+
+Project Structure:
+  The command will set up a project with the following structure:
+  - Proper configuration files for TypeScript and ESLint
+  - Dependencies for Powerhouse packages
+  - Build and development scripts
+
+Examples:
+  $ ph setup-globals my-project          # Create a new project named "my-project"
+  $ ph setup-globals                     # Set up a project in the current directory
+  $ ph setup-globals -i                  # Run setup in interactive mode
+  $ ph setup-globals --dev               # Use development version
+  $ ph setup-globals -v beta             # Use specific version
+  $ ph setup-globals --package-manager npm   # Use npm as package manager
+`;
+/**
+ * Help text for the init command
+ */
+export const initHelp = `
+Command Overview:
+  The init command creates a new Powerhouse project with optimal defaults. It sets up a fully 
+  configured project structure with all necessary dependencies, configurations, and boilerplate.
+
+  This command:
+  1. Creates a new project with the specified name
+  2. Installs all required dependencies for Powerhouse development
+  3. Sets up a proper project structure and configuration files
+  4. Can run in interactive mode for customized setup
+
+Arguments:
+  [project-name]        Optional. Name of the project to create. If not provided,
+                        you'll be prompted to provide a name, or the current directory 
+                        will be used if in interactive mode.
+
+Options:
+  -p, --project         Specify the name of the project to create.
+                        
+  -i, --interactive     Run the command in interactive mode, which will guide you
+                        through the project setup with customizable options.
+                        
+  -v, --version         Specify the development version to use. Defaults to "main".
+                        
+  --dev                 Use the "development" version of the boilerplate.
+                        
+  --staging             Use the "staging" version of the boilerplate.
+                        
+  --package-manager     Override the auto-detected package manager with the specified one.
+
+Project Structure:
+  The command will create a complete project with:
+  - Properly configured TypeScript and build settings
+  - Powerhouse document-model integration
+  - All necessary package.json dependencies
+  - Development scripts and tooling
+
+Examples:
+  $ ph init my-awesome-project                                # Create a new project named "my-awesome-project"
+  $ ph init -i                                                # Create a project in interactive mode
+  $ ph init -p my-project                                     # Same as ph init my-project
+  $ ph init --dev                                             # Use development version of boilerplate
+  $ ph init -v beta                                           # Use specific version
+  $ ph init --package-manager yarn                            # Use yarn as package manager
+  $ ph init my-awesome-project --dev --package-manager pnpm   # Create a project with Powerhouse dev packages and pnpm as package manager
+`;
+// Add other command help texts here as needed
+//# sourceMappingURL=help.js.map

package/dist/src/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/help.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCzB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CtB,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C/B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CvB,CAAC;AAEF,8CAA8C"}

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./commands/index.js";
-export * from "./utils.js";
+export * from "./utils/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -1,3 +1,3 @@
 export * from "./commands/index.js";
-export * from "./utils.js";
+export * from "./utils/index.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/src/utils/help-formatting.d.ts

@@ -0,0 +1,35 @@
+import { type Command } from "commander";
+export declare const HELP_FORMATTING_CONFIG: {
+    FIXED_COLUMN_WIDTH: number;
+    COMMANDS_TO_PAD: string[];
+    DESCRIPTION_PADDING: string;
+};
+/**
+ * Merges CLI help text with the forwarded PH CLI help text
+ * @param {string} cliHelp - Commander-generated help text
+ * @param {string} forwardedHelp - Help text from the PH CLI
+ * @returns {string} Merged help text
+ */
+export declare function mergeHelp(cliHelp: string, forwardedHelp: string): string;
+/**
+ * Applies padding to command descriptions for better alignment
+ * @param {Command} program - Commander program instance
+ */
+export declare function applyCommandPadding(program: Command): void;
+/**
+ * Restores original command descriptions after generating help
+ * @param {Command} program - Commander program instance
+ */
+export declare function restoreCommandDescriptions(program: Command): void;
+/**
+ * Captures Commander help output as a string
+ * @param {Command} program - Commander program instance
+ * @returns {string} Help text as a string
+ */
+export declare function captureCommanderHelp(program: Command): string;
+/**
+ * Generates and displays the merged help output
+ * @param {Command} program - Commander program instance
+ */
+export declare function generateMergedHelp(program: Command): Promise<void>;
+//# sourceMappingURL=help-formatting.d.ts.map

package/dist/src/utils/help-formatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatting.d.ts","sourceRoot":"","sources":["../../../src/utils/help-formatting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,eAAO,MAAM,sBAAsB;;;;CAOlC,CAAC;AAiEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CA2DxE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAS1D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAe7D;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BxE"}

package/dist/src/utils/help-formatting.js

@@ -0,0 +1,176 @@
+import { forwardPHCommand, getPackageManagerFromLockfile, getProjectInfo, } from "./index.js";
+// Configuration constants for help formatting
+export const HELP_FORMATTING_CONFIG = {
+    // Column width for command descriptions alignment
+    FIXED_COLUMN_WIDTH: 55,
+    // List of command names to apply padding to
+    COMMANDS_TO_PAD: ["setup-globals", "init", "use", "update", "help"],
+    // Padding to add before command descriptions for alignment
+    DESCRIPTION_PADDING: "            ",
+};
+/**
+ * Extracts command and description parts from a command line
+ * @param {string} line - A line from the help text containing a command
+ * @returns {{ cmd: string, desc: string }} Normalized command parts
+ */
+function extractCommandParts(line) {
+    // First try to match a command with options and arguments
+    let match = /^(\s+\S+(?:\|\S+)*(?:\s+\[options\])?(?:\s+\[[^\]]+\]|\s+<[^>]+>)*)(.*)$/.exec(line);
+    if (!match) {
+        // Fallback to a simpler pattern
+        match = /^(\s+\S+(?:\|\S+)*)(.*)$/.exec(line);
+    }
+    if (!match) {
+        return { cmd: line, desc: "" };
+    }
+    return {
+        cmd: match[1].trimEnd(),
+        desc: match[2].trim(),
+    };
+}
+/**
+ * Formats a command with proper description alignment
+ * @param {object} parts - Command parts with cmd and desc properties
+ * @param {number} columnWidth - Fixed position for descriptions to start
+ * @returns {string} Formatted command line
+ */
+function formatCommandLine({ cmd, desc }, columnWidth) {
+    // Calculate padding needed for alignment
+    const padding = " ".repeat(Math.max(2, columnWidth - cmd.length));
+    return `${cmd}${padding}${desc}`;
+}
+/**
+ * Extracts command lines from help text starting from the Commands section
+ * @param {string[]} lines - Help text split into lines
+ * @param {number} startIndex - Index of the Commands section header
+ * @returns {string[]} Array of command lines
+ */
+function extractCommandLines(lines, startIndex) {
+    const commands = [];
+    for (let i = startIndex + 1; i < lines.length; i++) {
+        const line = lines[i];
+        // Stop when we hit an empty line or no longer see command formatting
+        if (!line.trim() || !/^\s{2}\S/.exec(line)) {
+            break;
+        }
+        commands.push(line);
+    }
+    return commands;
+}
+/**
+ * Merges CLI help text with the forwarded PH CLI help text
+ * @param {string} cliHelp - Commander-generated help text
+ * @param {string} forwardedHelp - Help text from the PH CLI
+ * @returns {string} Merged help text
+ */
+export function mergeHelp(cliHelp, forwardedHelp) {
+    // Split help text into lines
+    const cliLines = cliHelp.split("\n");
+    const forwardedLines = forwardedHelp.split("\n");
+    // Find the Commands section in both help texts
+    const cliCommandsIndex = cliLines.findIndex((line) => line.trim() === "Commands:");
+    const forwardedCommandsIndex = forwardedLines.findIndex((line) => line.trim() === "Commands:");
+    // Extract command lines
+    const cliCommands = extractCommandLines(cliLines, cliCommandsIndex);
+    const forwardedCommands = extractCommandLines(forwardedLines, forwardedCommandsIndex);
+    // Create a set of CLI command names to avoid duplicates
+    const cliCommandNames = new Set();
+    cliCommands.forEach((line) => {
+        const match = /^\s+(\S+)(?:\|.*)?/.exec(line);
+        if (match)
+            cliCommandNames.add(match[1]);
+    });
+    // Filter out duplicate commands from forwarded help
+    const uniqueForwardedCommands = forwardedCommands.filter((line) => {
+        const match = /^\s+(\S+)(?:\|.*)?/.exec(line);
+        if (!match)
+            return false;
+        // Explicitly filter out 'help' command from forwarded commands
+        if (match[1] === "help")
+            return false;
+        return !cliCommandNames.has(match[1]);
+    });
+    // Process and format all commands
+    const cliParts = cliCommands.map(extractCommandParts);
+    const forwardedParts = uniqueForwardedCommands.map(extractCommandParts);
+    // Format with consistent alignment
+    const formattedCliCommands = cliParts.map((parts) => formatCommandLine(parts, HELP_FORMATTING_CONFIG.FIXED_COLUMN_WIDTH));
+    const formattedForwardedCommands = forwardedParts.map((parts) => formatCommandLine(parts, HELP_FORMATTING_CONFIG.FIXED_COLUMN_WIDTH));
+    // Extract header section
+    const headerSection = cliLines.slice(0, cliCommandsIndex + 1).join("\n");
+    // Combine all sections
+    return [
+        headerSection,
+        formattedCliCommands.join("\n"),
+        formattedForwardedCommands.join("\n"),
+    ].join("\n");
+}
+/**
+ * Applies padding to command descriptions for better alignment
+ * @param {Command} program - Commander program instance
+ */
+export function applyCommandPadding(program) {
+    program.commands.forEach((cmd) => {
+        if (HELP_FORMATTING_CONFIG.COMMANDS_TO_PAD.includes(cmd.name())) {
+            // Store original description in a property we can retrieve later
+            const desc = cmd.description();
+            // Add padding to the description
+            cmd.description(HELP_FORMATTING_CONFIG.DESCRIPTION_PADDING + desc);
+        }
+    });
+}
+/**
+ * Restores original command descriptions after generating help
+ * @param {Command} program - Commander program instance
+ */
+export function restoreCommandDescriptions(program) {
+    program.commands.forEach((cmd) => {
+        if (HELP_FORMATTING_CONFIG.COMMANDS_TO_PAD.includes(cmd.name())) {
+            const desc = cmd.description();
+            cmd.description(desc.trim());
+        }
+    });
+}
+/**
+ * Captures Commander help output as a string
+ * @param {Command} program - Commander program instance
+ * @returns {string} Help text as a string
+ */
+export function captureCommanderHelp(program) {
+    let helpText = "";
+    const originalConsoleLog = console.log;
+    // Override console.log to capture output
+    console.log = (...args) => {
+        helpText += args.join(" ") + "\n";
+    };
+    program.outputHelp();
+    // Restore console.log
+    console.log = originalConsoleLog;
+    return helpText;
+}
+/**
+ * Generates and displays the merged help output
+ * @param {Command} program - Commander program instance
+ */
+export async function generateMergedHelp(program) {
+    // Get project information
+    const projectInfo = await getProjectInfo(undefined, false);
+    if (projectInfo.available) {
+        const packageManager = getPackageManagerFromLockfile(projectInfo.path);
+        // Get forwarded help from PH CLI
+        const forwardedHelp = forwardPHCommand(packageManager, projectInfo.path, "help", undefined, true);
+        // Apply padding to command descriptions for better alignment
+        applyCommandPadding(program);
+        // Capture the output without displaying it
+        const helpText = captureCommanderHelp(program);
+        // Restore original descriptions
+        restoreCommandDescriptions(program);
+        // Merge and display help
+        const mergedHelp = mergeHelp(helpText, forwardedHelp);
+        console.log(mergedHelp);
+    }
+    else {
+        console.log(captureCommanderHelp(program));
+    }
+}
+//# sourceMappingURL=help-formatting.js.map

package/dist/src/utils/help-formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-formatting.js","sourceRoot":"","sources":["../../../src/utils/help-formatting.ts"],"names":[],"mappings":"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"}

package/dist/src/{utils.d.ts → utils/index.d.ts}

@@ -1,3 +1,5 @@
+import { type Command } from "commander";
+export * from "./help-formatting.js";
 export declare const PH_BIN_PATH: string;
 export declare const PH_BIN = "ph-cli";
 export declare const PH_CLI_COMMANDS: string[];
@@ -48,6 +50,7 @@ export declare const packageManagers: {
 };
 export type ProjectInfo = {
     isGlobal: boolean;
+    available: boolean;
     path: string;
 };
 export type PackageManager = "npm" | "yarn" | "pnpm" | "bun";
@@ -57,8 +60,8 @@ export declare function isPowerhouseProject(dir: string): boolean;
 export declare function findNodeProjectRoot(dir: string, pathValidation?: PathValidation): string | null;
 export declare function getPackageManagerFromPath(dir: string): PackageManager;
 export declare function getPackageManagerFromLockfile(dir: string): PackageManager;
-export declare function getProjectInfo(debug?: boolean): ProjectInfo;
-export declare function forwardPHCommand(packageManager: PackageManager, projectPath: string, args: string, debug?: boolean): void;
+export declare function getProjectInfo(debug?: boolean, generateGlobalProject?: boolean): Promise<ProjectInfo>;
+export declare function forwardPHCommand(packageManager: PackageManager, projectPath: string, args: string, debug?: boolean, captureOutput?: boolean): string;
 /**
  * Recursively searches for a specific file by traversing up the directory tree.
  * Starting from the given path, it checks each parent directory until it finds
@@ -77,5 +80,42 @@ export declare function forwardPHCommand(packageManager: PackageManager, project
  */
 export declare const findContainerDirectory: (startPath: string, targetFile: string) => string | null;
 export declare function installDependency(packageManager: PackageManager, dependencies: string[], projectPath: string, workspace?: boolean): void;
-export {};
-//# sourceMappingURL=utils.d.ts.map
+export type GlobalProjectOptions = {
+    project?: string;
+    interactive?: boolean;
+    version?: string;
+    dev?: boolean;
+    staging?: boolean;
+    packageManager?: string;
+};
+export declare const createGlobalProject: (projectName?: string, options?: GlobalProjectOptions) => Promise<void>;
+/**
+ * Helper to handle help flag detection for commands
+ * This centralizes the pattern of checking for help flags and showing command-specific help
+ *
+ * @param command - The Command instance
+ * @param actionFn - The original action function to call if help is not requested
+ * @returns A wrapped action function
+ */
+export declare function withHelpHandler<T extends unknown[]>(command: Command, actionFn: (...args: T) => Promise<void> | void): (...args: T) => Promise<void> | void;
+/**
+ * Simplified utility to connect a command with an action function that includes help handling
+ * This reduces boilerplate in command files by automatically setting up the action with help handling
+ *
+ * @param command - The Command instance
+ * @param actionFn - The action function to call when the command is executed
+ * @param preCheck - Optional validation function that runs before the action
+ * @returns The command for chaining
+ */
+export declare function withHelpAction<T extends unknown[]>(command: Command, actionFn: (...args: T) => Promise<void> | void, preCheck?: (...args: T) => boolean | undefined): Command;
+/**
+ * Enhanced version of withHelpAction that allows custom help text without duplication
+ *
+ * @param command - The Command instance
+ * @param actionFn - The action function to call when the command is executed
+ * @param helpText - The custom help text to display (replacing the auto-generated help)
+ * @param preCheck - Optional validation function that runs before the action
+ * @returns The command for chaining
+ */
+export declare function withCustomHelp<T extends unknown[]>(command: Command, actionFn: (...args: T) => Promise<void> | void, helpText: string, preCheck?: (...args: T) => boolean | undefined): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"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"}