@equinor/fusion-framework-cli 11.2.0 → 11.3.0

package/dist/types/bin/helpers/project-templates.schema.d.ts

@@ -0,0 +1,301 @@
+import { z } from 'zod';
+/**
+ * Zod schema for template resource files.
+ * Defines the structure for individual files in a project template.
+ */
+export declare const TemplateResourceFileSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "file";
+    target?: string | undefined;
+}, {
+    path: string;
+    type: "file";
+    target?: string | undefined;
+}>;
+/**
+ * Zod schema for template resource directories.
+ * Defines the structure for directories in a project template.
+ */
+export declare const TemplateResourceDirSchema: z.ZodObject<{
+    type: z.ZodLiteral<"dir">;
+    path: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "dir";
+    target?: string | undefined;
+    recursive?: boolean | undefined;
+}, {
+    path: string;
+    type: "dir";
+    target?: string | undefined;
+    recursive?: boolean | undefined;
+}>;
+/**
+ * Union schema for all template resource types.
+ * Supports both file and directory resources with discriminated union.
+ */
+export declare const TemplateResourceSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "file";
+    target?: string | undefined;
+}, {
+    path: string;
+    type: "file";
+    target?: string | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"dir">;
+    path: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    recursive: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    type: "dir";
+    target?: string | undefined;
+    recursive?: boolean | undefined;
+}, {
+    path: string;
+    type: "dir";
+    target?: string | undefined;
+    recursive?: boolean | undefined;
+}>]>;
+/**
+ * Zod schema for a single template item.
+ * Defines the structure of individual project templates.
+ */
+export declare const TemplateItemSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    resources: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        path: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    }, {
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"dir">;
+        path: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+        recursive: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    }, {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    resources: ({
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    } | {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    })[];
+    name: string;
+    description: string;
+}, {
+    resources: ({
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    } | {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    })[];
+    name: string;
+    description: string;
+}>;
+/**
+ * Zod schema for the complete templates manifest.
+ * Defines the structure of the templates.json file.
+ */
+export declare const TemplatesManifestSchema: z.ZodObject<{
+    templates: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        resources: z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            path: z.ZodString;
+            target: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        }, {
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"dir">;
+            path: z.ZodString;
+            target: z.ZodOptional<z.ZodString>;
+            recursive: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        }, {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        resources: ({
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        } | {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        })[];
+        name: string;
+        description: string;
+    }, {
+        resources: ({
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        } | {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        })[];
+        name: string;
+        description: string;
+    }>, "many">;
+    resources: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        path: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    }, {
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"dir">;
+        path: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+        recursive: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    }, {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    }>]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    templates: {
+        resources: ({
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        } | {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        })[];
+        name: string;
+        description: string;
+    }[];
+    resources?: ({
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    } | {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    })[] | undefined;
+}, {
+    templates: {
+        resources: ({
+            path: string;
+            type: "file";
+            target?: string | undefined;
+        } | {
+            path: string;
+            type: "dir";
+            target?: string | undefined;
+            recursive?: boolean | undefined;
+        })[];
+        name: string;
+        description: string;
+    }[];
+    resources?: ({
+        path: string;
+        type: "file";
+        target?: string | undefined;
+    } | {
+        path: string;
+        type: "dir";
+        target?: string | undefined;
+        recursive?: boolean | undefined;
+    })[] | undefined;
+}>;
+/**
+ * Type definitions derived from schemas
+ */
+export type TemplateResourceFile = z.infer<typeof TemplateResourceFileSchema>;
+export type TemplateResourceDir = z.infer<typeof TemplateResourceDirSchema>;
+export type TemplateResource = z.infer<typeof TemplateResourceSchema>;
+export type TemplateItem = z.infer<typeof TemplateItemSchema>;
+export type TemplatesManifest = z.infer<typeof TemplatesManifestSchema>;
+/**
+ * Validates and parses a template manifest JSON string.
+ *
+ * This function takes a JSON string containing template definitions and validates
+ * it against the TemplatesManifestSchema. It provides detailed error messages
+ * for both JSON parsing errors and schema validation failures.
+ *
+ * @param jsonString - The JSON string to validate and parse
+ * @returns Parsed and validated template manifest object
+ * @throws {Error} If JSON parsing fails or schema validation fails
+ *
+ * @example
+ * ```typescript
+ * const manifestJson = readFileSync('templates.json', 'utf8');
+ * const manifest = parseTemplatesManifest(manifestJson);
+ * console.log(`Found ${manifest.templates.length} templates`);
+ * ```
+ */
+export declare function parseTemplatesManifest(jsonString: string): TemplatesManifest;

package/dist/types/cli/commands/create/_helpers/check-target-directory.d.ts

@@ -0,0 +1,12 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Check if target directory exists and has content, then prompt user for action.
+ *
+ * @param targetDir - Directory to check
+ * @param logger - Logger instance for output
+ * @param clean - If true, automatically clean the directory without prompting
+ * @param baseDir - Base directory for path validation (defaults to process.cwd())
+ * @returns Promise resolving to true if should continue, false if should abort
+ */
+export declare function checkTargetDirectory(targetDir: string, logger: ConsoleLogger, clean?: boolean, baseDir?: string): Promise<boolean>;
+export default checkTargetDirectory;

package/dist/types/cli/commands/create/_helpers/cleanup-template-files.d.ts

@@ -0,0 +1,15 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+import type { ProjectTemplateRepository } from '../../../../bin/helpers/ProjectTemplateRepository.js';
+/**
+ * Prompts the user to clean up temporary template files after project creation.
+ *
+ * Offers the user the option to remove the cloned template repository and
+ * temporary files to free up disk space. If the user declines, the files
+ * remain available for future use.
+ *
+ * @param repo - ProjectTemplateRepository instance containing temporary files
+ * @param logger - Console logger for displaying prompts and cleanup status
+ * @returns Promise that resolves when the cleanup process is complete
+ */
+export declare function cleanupTemplateFiles(repo: ProjectTemplateRepository, logger: ConsoleLogger): Promise<void>;
+export default cleanupTemplateFiles;

package/dist/types/cli/commands/create/_helpers/install-dependencies.d.ts

@@ -0,0 +1,14 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Prompt user to install dependencies and execute the installation.
+ * Returns whether dependencies were actually installed and the package manager used.
+ *
+ * @param targetDir - Directory path where dependencies should be installed
+ * @param logger - Logger instance for output
+ * @returns Promise resolving to object with installed status and package manager
+ */
+export declare function installDependencies(targetDir: string, logger: ConsoleLogger): Promise<{
+    installed: boolean;
+    packageManager?: string;
+}>;
+export default installDependencies;

package/dist/types/cli/commands/create/_helpers/open-in-ide.d.ts

@@ -0,0 +1,15 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Prompts the user to open the newly created project in their preferred IDE.
+ *
+ * Displays a selection menu with supported IDEs (VS Code, Cursor) and executes
+ * the appropriate command to open the project directory. The IDE runs detached
+ * and independently of the CLI process. If the user chooses not to open an IDE,
+ * the function completes without action.
+ *
+ * @param targetDir - Absolute path to the project directory to open
+ * @param logger - Console logger for displaying prompts and instructions
+ * @returns Promise that resolves when the IDE selection process is complete
+ */
+export declare function openInIDE(targetDir: string, logger: ConsoleLogger): Promise<void>;
+export default openInIDE;

package/dist/types/cli/commands/create/_helpers/resolve-workspace-dependencies.d.ts

@@ -0,0 +1,27 @@
+import type { PackageJson } from 'type-fest';
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Resolves workspace dependencies in a package.json object to their latest npm versions.
+ *
+ * This function processes all dependency types (dependencies, devDependencies, peerDependencies)
+ * and replaces workspace dependencies (e.g., "workspace:^") with their latest available versions
+ * from the npm registry. It processes all dependency types in parallel for optimal performance.
+ *
+ * @param packageJson - The package.json object to modify (modified in place)
+ * @param logger - Optional logger for progress feedback and debugging
+ * @throws {Error} If version resolution fails for critical dependencies
+ *
+ * @example
+ * ```typescript
+ * const packageJson = {
+ *   dependencies: {
+ *     "@equinor/fusion-framework": "workspace:^",
+ *     "react": "^18.0.0"
+ *   }
+ * };
+ *
+ * await resolvePackageJsonWorkspaceDependencies(packageJson, logger);
+ * // packageJson.dependencies["@equinor/fusion-framework"] is now "1.0.0"
+ * ```
+ */
+export declare function resolvePackageJsonWorkspaceDependencies(packageJson: PackageJson, logger?: ConsoleLogger): Promise<void>;

package/dist/types/cli/commands/create/_helpers/select-template.d.ts

@@ -0,0 +1,24 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+import type { ProjectTemplate } from '../../../../bin/helpers/ProjectTemplate.js';
+/**
+ * Selects a template from the available templates with intelligent fallback logic.
+ *
+ * This function handles three scenarios:
+ * 1. Pre-selected template: Returns the specified template if valid
+ * 2. Single template: Automatically selects if only one template is available
+ * 3. Multiple templates: Prompts user to choose from a list
+ *
+ * @param templates - Array of available project templates
+ * @param preSelectedTemplate - Optional pre-selected template name from CLI option
+ * @param logger - Optional logger instance for debug output
+ * @returns Promise resolving to the selected template
+ * @throws {AssertionError} If templates array is empty or pre-selected template is invalid
+ *
+ * @example
+ * ```typescript
+ * const templates = await repo.getAvailableTemplates();
+ * const selected = await selectTemplate(templates, 'react-app', logger);
+ * ```
+ */
+export declare function selectTemplate(templates: ProjectTemplate[], preSelectedTemplate?: string, logger?: ConsoleLogger): Promise<ProjectTemplate>;
+export default selectTemplate;

package/dist/types/cli/commands/create/_helpers/setup-repository.d.ts

@@ -0,0 +1,23 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+import { ProjectTemplateRepository } from '../../../../bin/helpers/ProjectTemplateRepository.js';
+/**
+ * Sets up and initializes a project template repository for template access.
+ *
+ * This function creates a ProjectTemplateRepository instance and handles
+ * the complete initialization process, including optional cleanup of existing
+ * repository directories.
+ *
+ * @param templateRepoName - Name of the template repository (e.g., 'equinor/fusion-app-template')
+ * @param clean - Whether to clean the repo directory before cloning (removes existing directory)
+ * @param branch - Git branch to checkout (defaults to 'main')
+ * @param logger - Logger instance for output and debugging
+ * @returns Promise resolving to the initialized repository ready for template access
+ *
+ * @example
+ * ```typescript
+ * const repo = await setupRepository('equinor/fusion-app-template', true, 'main', logger);
+ * const templates = await repo.getAvailableTemplates();
+ * ```
+ */
+export declare function setupRepository(templateRepoName: string, clean: boolean, branch: string, logger: ConsoleLogger): Promise<ProjectTemplateRepository>;
+export default setupRepository;

package/dist/types/cli/commands/create/_helpers/start-dev-server.d.ts

@@ -0,0 +1,17 @@
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Prompts the user to start the development server after project creation.
+ *
+ * Offers the user the option to immediately start the development server
+ * using their selected package manager. The server runs in the foreground
+ * and can be stopped with Ctrl+C. When persistent mode is enabled, the server
+ * will run indefinitely until manually terminated by the user.
+ *
+ * @param targetDir - Absolute path to the project directory where dev server should start
+ * @param packageManager - Package manager command to use (e.g., 'pnpm', 'npm')
+ * @param logger - Console logger for displaying prompts and server status
+ * @param persistent - If true, runs the dev server indefinitely without timeout (default: false)
+ * @returns Promise resolving to true if dev server was started, false if user skipped
+ */
+export declare function startDevServer(targetDir: string, packageManager: string, logger: ConsoleLogger, persistent?: boolean): Promise<boolean>;
+export default startDevServer;

package/dist/types/cli/commands/create/_helpers/update-package-json.d.ts

@@ -0,0 +1,41 @@
+import type { PackageJson } from 'type-fest';
+import type { ConsoleLogger } from '@equinor/fusion-framework-cli/bin';
+/**
+ * Options for updating package.json
+ */
+interface UpdatePackageJsonOptions {
+    /** Whether to resolve workspace dependencies to npm versions */
+    resolveWorkspaceDependencies?: boolean;
+    /** Properties to update in package.json */
+    updates?: Partial<PackageJson>;
+}
+/**
+ * Updates the package.json file with the provided properties and resolves workspace dependencies.
+ *
+ * This function reads the package.json file from the target directory, optionally resolves
+ * workspace dependencies to their latest npm versions, applies property updates, and writes
+ * the updated content back to the file. It preserves the original formatting and structure.
+ *
+ * @param targetDir - The target directory containing the package.json file
+ * @param options - Configuration options for the update operation
+ * @param options.resolveWorkspaceDependencies - Whether to resolve workspace dependencies to npm versions
+ * @param options.updates - Properties to update in package.json
+ * @param logger - Optional logger for progress feedback and debugging
+ * @throws {Error} If package.json cannot be read, parsed, or written
+ *
+ * @example
+ * ```typescript
+ * // Update just the name
+ * await updatePackageJson('/path/to/project', {
+ *   updates: { name: 'my-new-app' }
+ * });
+ *
+ * // Update multiple properties and resolve workspace deps
+ * await updatePackageJson('/path/to/project', {
+ *   updates: { name: 'my-new-app', version: '1.0.0' },
+ *   resolveWorkspaceDependencies: true
+ * }, logger);
+ * ```
+ */
+export declare const updatePackageJson: (targetDir: string, options?: UpdatePackageJsonOptions, logger?: ConsoleLogger) => Promise<void>;
+export {};

package/dist/types/cli/commands/create/app.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CLI command for creating new Fusion Framework applications from templates.
+ *
+ * This command provides a comprehensive interactive workflow for:
+ * - Validating input and resolving directory conflicts
+ * - Selecting from available project templates (React, vanilla, etc.)
+ * - Setting up complete local development environment
+ * - Resolving workspace dependencies to npm versions
+ * - Installing dependencies and starting development servers
+ * - Opening projects in the user's preferred IDE
+ *
+ * @example
+ * ```bash
+ * # Create a new React app with interactive template selection
+ * ffc create app my-new-app
+ *
+ * # Create with a specific template
+ * ffc create app my-app --template react-app
+ *
+ * # Create in a specific directory with debug logging
+ * ffc create app my-app --directory ./projects --debug
+ *
+ * # Create with clean directory and specific branch
+ * ffc create app my-app --clean --branch develop
+ * ```
+ */
+export declare const createAppCommand: (name: string) => import("commander").Command;
+export default createAppCommand;

package/dist/types/cli/commands/create/index.d.ts

@@ -0,0 +1,2 @@
+export declare const command: import("commander").Command;
+export default command;

package/dist/types/lib/utils/assert.d.ts

@@ -1,34 +1,65 @@
 import assert, { AssertionError } from 'node:assert';
 /**
  * Re-exports the core Node.js assert function and AssertionError class.
- * Useful for consistent assertion handling throughout the codebase.
+ *
+ * This provides consistent assertion handling throughout the codebase
+ * with proper TypeScript type narrowing support.
  */
 export { assert, AssertionError };
 /**
  * Asserts that the provided value is a valid number (not NaN).
- * Throws an AssertionError if the value is not a number.
  *
- * @param value - The value to check for being a number.
- * @param message - Optional custom error message for assertion failure.
- * @throws {AssertionError} If value is NaN.
+ * This function checks that the value is not NaN, which is useful for
+ * validating numeric inputs that might be strings or other types that
+ * could convert to NaN.
+ *
+ * @param value - The value to check for being a valid number
+ * @param message - Optional custom error message for assertion failure
+ * @throws {AssertionError} If value is NaN
+ *
+ * @example
+ * ```typescript
+ * assertNumber(42); // ✅ Passes
+ * assertNumber('42'); // ✅ Passes (string converts to number)
+ * assertNumber(NaN); // ❌ Throws AssertionError
+ * assertNumber('invalid'); // ❌ Throws AssertionError
+ * ```
  */
 export declare function assertNumber(value: unknown, message?: string): asserts value;
 /**
  * Asserts that a file exists at the given path.
- * Throws an error if the file does not exist.
  *
- * @param value - The file path to check.
- * @param message - Optional custom error message for assertion failure.
- * @throws {AssertionError} If the file does not exist.
+ * This function uses the fileExists utility to check for file presence
+ * and throws an AssertionError if the file is not found.
+ *
+ * @param value - The file path to check
+ * @param message - Optional custom error message for assertion failure
+ * @throws {AssertionError} If the file does not exist
+ *
+ * @example
+ * ```typescript
+ * assertFileExists('/path/to/file.txt'); // ✅ Passes if file exists
+ * assertFileExists('/nonexistent/file.txt'); // ❌ Throws AssertionError
+ * ```
  */
 export declare const assertFileExists: (value: unknown, message?: string) => asserts value;
 /**
  * Asserts that the provided value is an object.
- * Throws an error if the value is not an object.
  *
- * @param value - The value to check for being an object.
- * @param message - Optional custom error message or Error instance.
- * @throws {AssertionError} If value is not an object.
+ * This function checks that the value has type 'object'. Note that
+ * typeof null is 'object' in JavaScript, so null values will pass this check.
+ *
+ * @param value - The value to check for being an object
+ * @param message - Optional custom error message or Error instance
+ * @throws {AssertionError} If value is not an object
+ *
+ * @example
+ * ```typescript
+ * assertObject({}); // ✅ Passes
+ * assertObject([]); // ✅ Passes
+ * assertObject(null); // ✅ Passes (typeof null === 'object')
+ * assertObject('string'); // ❌ Throws AssertionError
+ * ```
  */
 export declare function assertObject(value: object, message?: string | Error): asserts value;
 /**
@@ -56,3 +87,20 @@ export declare function assertObjectEntries<T extends object, P extends Array<ke
     assertion?: typeof assertObjectEntryValue;
     preMessage?: string;
 }): asserts value;
+/**
+ * Asserts that a directory exists and is a valid git repository.
+ *
+ * This function checks if the specified directory contains a valid
+ * git repository by looking for the .git directory or file.
+ *
+ * @param dir - Directory path to check for git repository
+ * @param message - Optional custom error message for assertion failure
+ * @throws {AssertionError} If the directory is not a git repository
+ *
+ * @example
+ * ```typescript
+ * assertGitRepository('/path/to/git/repo'); // ✅ Passes if .git exists
+ * assertGitRepository('/path/to/regular/dir'); // ❌ Throws AssertionError
+ * ```
+ */
+export declare function assertGitRepository(dir: string, message?: string): void;

package/dist/types/lib/utils/is-git-dir.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if a directory exists and is a valid git repository.
+ *
+ * @param dir - Directory path to check.
+ * @returns True if the directory exists and is a git repository, false otherwise.
+ * @public
+ */
+export declare function isGitDir(dir: string): boolean;
+export default isGitDir;