kist 0.0.0 → 0.1.31

package/ts/interface/PackageJson.ts

@@ -0,0 +1,171 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+// import { Record, string, optional, array, union } from 'runtypes';
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * TypeScript interface describing the structure of a package.json file.
+ * This interface includes all standard fields used by npm, as well as common
+ * fields used by related tools like Yarn, and can be extended with custom
+ * fields as needed.
+ */
+export interface PackageJson {
+    // The name of the package.
+    name: string;
+
+    // The version of the package.
+    version: string;
+
+    // A brief description of the package.
+    description?: string;
+
+    // The entry point for the package.
+    main?: string;
+
+    // Scripts that can be executed with npm/yarn.
+    scripts?: Record<string, string>;
+
+    // Production dependencies of the package.
+    dependencies?: Record<string, string>;
+
+    // Development dependencies of the package.
+    devDependencies?: Record<string, string>;
+
+    // Repository information for the package.
+    repository?: {
+        type: string;
+        url: string;
+    };
+
+    // Keywords associated with the package.
+    keywords?: string[];
+
+    // The author of the package.
+    author?:
+        | string
+        | {
+              name: string;
+              email?: string;
+              url?: string;
+          };
+
+    // The license under which the package is provided.
+    license?: string;
+
+    // Links to the package bug tracker.
+    bugs?: {
+        url?: string;
+        email?: string;
+    };
+
+    // The URL to the homepage of the package.
+    homepage?: string;
+
+    // Indicates if the package should be published.
+    private?: boolean;
+
+    // Peer dependencies of the package.
+    peerDependencies?: Record<string, string>;
+
+    // Engine requirements for the package.
+    engines?: {
+        node?: string;
+        npm?: string;
+    };
+
+    // Executable files included with the package.
+    bin?: Record<string, string>;
+
+    // Path to the TypeScript declaration files.
+    types?: string;
+
+    // Other contributors to the package.
+    contributors?: Array<
+        | string
+        | {
+              name: string;
+              email?: string;
+              url?: string;
+          }
+    >;
+
+    // Funding information for the package.
+    funding?:
+        | string
+        | {
+              type: string;
+              url: string;
+          };
+
+    // An array of file patterns included in the package.
+    files?: string[];
+
+    // Target browsers/environments for tools like Babel.
+    browserslist?: string[] | Record<string, string[]>;
+
+    // Configuration for publishing the package.
+    publishConfig?: Record<string, any>;
+
+    // Configuration parameters used in scripts.
+    config?: Record<string, any>;
+
+    // Alternative to "types", path to TypeScript declaration files.
+    typings?: string;
+
+    // Define export map for submodules and conditions.
+    exports?: Record<string, any>;
+
+    // Specify an ES module entry point.
+    module?: string;
+
+    // Indicate which modules in the package have side effects.
+    sideEffects?: boolean | string[];
+
+    // Optional dependencies.
+    optionalDependencies?: Record<string, string>;
+
+    // Dependencies to be bundled with the package.
+    bundledDependencies?: string[];
+
+    // Metadata for peer dependencies.
+    peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+
+    // Dependency resolution hints for yarn.
+    resolutions?: Record<string, string>;
+
+    // Workspace configuration for managing multiple packages.
+    workspaces?:
+        | string[]
+        | {
+              packages: string[];
+          };
+
+    // ESLint configuration embedded in package.json.
+    eslintConfig?: Record<string, any>;
+
+    // Babel configuration embedded in package.json.
+    babel?: Record<string, any>;
+
+    // Prettier configuration embedded in package.json.
+    prettier?: Record<string, any>;
+
+    // Husky configuration for Git hooks.
+    husky?: Record<string, any>;
+
+    // Jest configuration for unit tests.
+    jest?: Record<string, any>;
+
+    // Enforce engine requirements strictly.
+    enginesStrict?: boolean;
+
+    // Specify OS compatibility.
+    os?: string[];
+
+    // Specify CPU architecture compatibility.
+    cpu?: string[];
+}

package/ts/interface/PipelineOptionsInterface.ts

@@ -0,0 +1,74 @@
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * PipelineOptionsInterface defines settings for managing the pipeline's
+ * execution behavior, including timeouts, failure handling, concurrency,
+ * and retry strategies.
+ */
+export interface PipelineOptionsInterface {
+    /**
+     * Default timeout in milliseconds for each step within the pipeline.
+     *
+     * If a step exceeds this duration, it will be forcibly terminated to
+     * prevent blocking the pipeline. This setting helps manage steps that
+     * might hang or take longer than expected.
+     *
+     * @default 30000
+     * @example 15000
+     */
+    stepTimeout?: number;
+
+    /**
+     * Specifies whether to halt the entire pipeline if a step fails.
+     * - true: The pipeline will stop execution immediately upon encountering
+     *      a failed step.
+     * - false: The pipeline will continue executing subsequent steps and
+     *      stages despite errors.
+     *
+     * Default is true (halt on failure), ensuring the pipeline stops at the
+     * first sign of trouble.
+     *
+     * @default true
+     */
+    haltOnFailure?: boolean;
+
+    /**
+     * Specifies the maximum number of concurrent stages allowed to run in
+     * parallel. This setting controls resource usage and can help prevent
+     * overloading the system.
+     *
+     * - `0` or `undefined`: No limit, all stages run in parallel (as allowed
+     *   by their dependencies).
+     * - A positive integer: Limits the number of stages that can run
+     *   simultaneously.
+     *
+     * @default undefined
+     */
+    maxConcurrentStages?: number;
+
+    /**
+     * Specifies a retry strategy for steps that fail.
+     *
+     * - `retries`: Number of retry attempts before marking a step as failed.
+     * - `delay`: Time in milliseconds between retry attempts.
+     *
+     * This allows automatic retries for temporary failures, improving
+     * pipeline robustness.
+     *
+     * @default { retries: 0, delay: 0 }
+     * @example { retries: 3, delay: 1000 }
+     */
+    retryStrategy?: {
+        /**
+         * Number of retry attempts before marking a step as failed.
+         */
+        retries: number;
+
+        /**
+         * Time in milliseconds between retry attempts.
+         */
+        delay: number;
+    };
+}

package/ts/interface/SVG.ts

@@ -0,0 +1,84 @@
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+// export interface Svg {
+//     metadata: {
+//     name: string;
+//     // ... other metadata properties
+//     };
+//     source: string;
+//     // ... other Svg properties
+// }
+
+/**
+ * Represents the metadata associated with an SVG graphic.
+ */
+interface SvgMetadata {
+    // The name of the SVG graphic.
+    name: string;
+    // Optional creator of the SVG graphic.
+    creator?: string;
+    // Optional description of the SVG graphic.
+    description?: string;
+    // Optional license information for the SVG graphic.
+    license?: string;
+}
+
+/**
+ * Represents an SVG (Scalable Vector Graphics) object.
+ */
+export interface Svg {
+    // Metadata associated with the SVG.
+    metadata: SvgMetadata;
+    // The SVG content as a string.
+    source: string;
+    // Optional width of the SVG graphic.
+    width?: number;
+    // Optional height of the SVG graphic.
+    height?: number;
+    // Optional 'viewBox' attribute that defines the position and dimension,
+    // in user space, of an SVG viewport.
+    viewBox?: string;
+    // Optional array of path data (for more detailed manipulation or data
+    // extraction).
+    paths?: SvgPath[];
+}
+
+/**
+ * Represents the path element within an SVG, detailing its specific properties.
+ */
+interface SvgPath {
+    // Path data (the "d" attribute).
+    d: string;
+    // Optional fill color.
+    fill?: string;
+    // Optional stroke color.
+    stroke?: string;
+    // Optional stroke width.
+    strokeWidth?: number;
+}
+
+/**
+ * Example usage of the Svg interface.
+ */
+const exampleSvg: Svg = {
+    metadata: {
+        name: "Example SVG",
+        creator: "Example Creator",
+        description: "A sample SVG file",
+        license: "MIT",
+    },
+    source: '<svg width="100" height="100">...</svg>',
+    width: 100,
+    height: 100,
+    viewBox: "0 0 100 100",
+    paths: [
+        {
+            d: "M10 10 H 90 V 90 H 10 L 10 10",
+            fill: "none",
+            stroke: "black",
+            strokeWidth: 2,
+        },
+    ],
+};

package/ts/interface/StageInterface.ts

@@ -0,0 +1,96 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { StepInterface } from "./StepInterface";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * StageInterface represents a stage in the packaging pipeline, consisting of
+ * multiple steps. Each stage serves as a logical grouping of related steps,
+ * providing a structured way to organize the pipeline execution flow. Stages
+ * can have dependencies on other stages, allowing for complex sequencing of
+ * actions within the pipeline.
+ */
+export interface StageInterface {
+    /**
+     * A unique identifier for the stage, used for logging, tracking, and
+     * reporting purposes. The name should be descriptive enough to clearly
+     * convey the purpose of the stage.
+     */
+    name: string;
+
+    /**
+     * An ordered array of steps that comprise the stage.
+     * Steps are executed consecutively within the stage, following the order
+     * they are defined in. Each step is expected to implement the
+     * StepInterface, providing specific actions to be performed.
+     */
+    steps: StepInterface[];
+
+    /**
+     * An optional list of stage names that this stage depends on.
+     * The current stage will not begin execution until all specified dependent
+     * stages have completed successfully. This allows for orchestrating
+     * complex dependencies and ensuring proper sequencing of stages in the
+     * pipeline.
+     */
+    dependsOn?: string[];
+
+    /**
+     * An optional description of the stage, providing additional context and
+     * details about what the stage is intended to accomplish. Useful for
+     * documentation, logging, and understanding the overall pipeline flow.
+     */
+    description?: string;
+
+    /**
+     * An optional flag to control whether the stage should be executed.
+     * This can be used to conditionally skip stages based on dynamic criteria,
+     * such as environment settings or previous results.
+     * Default is true (stage will be executed).
+     */
+    enabled?: boolean;
+
+    /**
+     * Optional timeout for the entire stage, specified in milliseconds.
+     * If the stage exceeds this duration, it will be forcibly terminated to
+     * prevent blocking the pipeline indefinitely. Helps manage long-running
+     * stages and ensures the pipeline maintains predictable execution times.
+     */
+    timeout?: number;
+
+    /**
+     * Priority level for the stage, used to influence execution order in
+     * concurrent scenarios. Higher priority stages may execute before lower
+     * priority ones when multiple stages are eligible to run simultaneously.
+     * Default: `'normal'`.
+     * - `'low'`: Lower execution priority.
+     * - `'normal'`: Default execution priority.
+     * - `'high'`: Higher execution priority.
+     */
+    priority?: "low" | "normal" | "high";
+
+    /**
+     * Optional tags to attach metadata or labels to the stage. Tags can be
+     * used for filtering, reporting, or integration with external tools that
+     * require context or categorization.
+     */
+    tags?: Record<string, string>;
+
+    /**
+     * Optional hooks that allow custom logic to be executed before or after
+     * the stage.
+     * Useful for injecting custom behavior or performing additional
+     * setup/cleanup tasks.
+     * - `before`: Function to run before the stage starts.
+     * - `after`: Function to run after the stage completes.
+     */
+    hooks?: {
+        before?: () => Promise<void> | void;
+        after?: () => Promise<void> | void;
+    };
+}

package/ts/interface/StepInterface.ts

@@ -0,0 +1,83 @@
+// ============================================================================
+// Import
+// ============================================================================
+
+import { ActionInterface } from "./ActionInterface";
+import { StepOptionsInterface } from "./StepOptionsInterface";
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * StepInterface defines a single executable unit within a pipeline stage.
+ * Each step encapsulates a specific action to be performed, along with
+ * configuration options that tailor its behavior. Steps are executed in
+ * sequence within their respective stages.
+ */
+export interface StepInterface {
+    /**
+     * A unique identifier for the step, used for logging, debugging, and
+     * reporting. This name should be descriptive and clearly indicate the
+     * purpose of the step.
+     */
+    name: string;
+
+    /**
+     * The action that this step will perform, represented by a class
+     * implementing the ActionInterface. This action defines the core
+     * functionality of the step, such as building, testing, or deploying.
+     * The action is responsible for executing the main logic associated with
+     * the step.
+     */
+    action: ActionInterface;
+    // action: string; // Name of the action to perform (matches registry).
+
+    /**
+     * Optional configuration options specific to the step.
+     * These options allow customization of the step's behavior, providing
+     * flexibility to adapt the action to different contexts or requirements.
+     * For example, build steps might accept options for minification or target
+     * environments.
+     */
+    options?: StepOptionsInterface;
+
+    /**
+     * An optional flag to enable or disable this step dynamically.
+     * - `true`: Step will be executed (default behavior).
+     * - `false`: Step will be skipped during execution.
+     */
+    enabled?: boolean;
+
+    /**
+     * Optional timeout for this step, specified in milliseconds.
+     * If the step exceeds this duration, it will be forcibly terminated,
+     * ensuring the pipeline remains predictable and responsive.
+     */
+    timeout?: number;
+
+    /**
+     * An optional description providing additional context or details about
+     * the step. Useful for documentation, reporting, or explaining the
+     * purpose of the step to maintainers.
+     */
+    description?: string;
+
+    /**
+     * An optional set of tags to provide metadata for the step.
+     * Tags can be used for logging, filtering, or integrating with external
+     * tools and systems that require context.
+     */
+    tags?: Record<string, string>;
+
+    /**
+     * Optional hooks to execute custom logic before or after the step.
+     * Hooks can be used for additional setup, teardown, or condition checks.
+     * - `before`: Function executed before the step runs.
+     * - `after`: Function executed after the step completes.
+     */
+    hooks?: {
+        before?: () => Promise<void> | void;
+        after?: () => Promise<void> | void;
+    };
+}

package/ts/interface/StepOptionsInterface.ts

@@ -0,0 +1,57 @@
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+/**
+ * StepOptionsInterface represents the configuration options for a step,
+ * allowing customization of the step's behavior through specific parameters
+ * and settings. This interface can be extended for action-specific options,
+ * providing type safety and clarity for different configurations used within
+ * the packaging pipeline.
+ */
+export interface StepOptionsInterface {
+    /**
+     * An optional description of the step, useful for logging, debugging, and
+     * reporting. This provides additional context about the step's purpose and
+     * configuration.
+     */
+    description?: string;
+
+    /**
+     * Specifies whether the step should be enabled or skipped.
+     * This can be used to conditionally execute steps based on dynamic
+     * criteria.
+     * Default is true (enabled).
+     */
+    enabled?: boolean;
+
+    /**
+     * A flexible map of key-value pairs representing configuration settings
+     * specific to the step. Each action can define its own expected structure
+     * for these options, enabling fine-grained control.
+     *
+     * Examples:
+     * - Build step: `{ minify: true, target: 'es6', sourceMap: false }`
+     * - Test step: `{ framework: 'jest', coverage: true, timeout: 3000 }`
+     *
+     * This generic structure ensures compatibility with a wide range of use cases.
+     */
+    // [key: string]: unknown; // Generic key-value pairs to support diverse options.
+}
+
+/**
+ * Recommendations for Extending StepOptionsInterface:
+ * - For specific actions, extend `StepOptionsInterface` to add detailed types
+ *   and enforce stricter validation.
+ *
+ * Example:
+ * ```typescript
+ * export interface BuildStepOptions extends StepOptionsInterface {
+ *     minify?: boolean;
+ *     target?: 'es5' | 'es6' | 'es2020';
+ *     sourceMap?: boolean;
+ * }
+ * ```
+ *
+ * This approach ensures type safety while maintaining flexibility for general steps.
+ */

package/ts/interface/index.ts

@@ -0,0 +1,9 @@
+// Exporting all interfaces from the interfaces directory
+
+export { ActionInterface } from "./ActionInterface";
+export { ConfigInterface } from "./ConfigInterface";
+export { LiveOptionsInterface } from "./LiveOptionsInterface";
+export { OptionsInterface } from "./OptionsInterface";
+export { StageInterface } from "./StageInterface";
+export { StepInterface } from "./StepInterface";
+export { StepOptionsInterface } from "./StepOptionsInterface";