Kist Action Template

Template repository for creating kist action plugins.

Quick Start

1. Use This Template

Click "Use this template" on GitHub or clone this repository:

git clone https://github.com/yourusername/kist-action-template.git my-kist-action
cd my-kist-action

2. Customize Your Action

1. Update package.json:

   • Change name to @getkist/action-yourname or kist-action-yourname
   • Update description, author, repository, and keywords
   • Set appropriate version (start with 0.1.0 or 1.0.0)

2. Rename the Action:

   • Rename src/actions/ExampleAction.ts to your action name
   • Update the class name and implementation
   • Update exports in src/index.ts

3. Update Documentation:

   • Modify this README with your action's documentation
   • Update LICENSE if needed

3. Install Dependencies

npm install

4. Develop Your Action

# Build TypeScript
npm run build

# Watch mode for development
npm run build:watch

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Check test coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

Project Structure

kist-action-template/
├── src/
│   ├── actions/
│   │   ├── ExampleAction.ts       # Action implementation
│   │   └── ExampleAction.test.ts  # Action tests
│   └── index.ts                    # Plugin entry point
├── dist/                           # Compiled output (generated)
├── .eslintrc.json                  # ESLint configuration
├── .prettierrc                     # Prettier configuration
├── jest.config.js                  # Jest configuration
├── tsconfig.json                   # TypeScript configuration
├── package.json
├── README.md
└── LICENSE

Creating Your Action

1. Implement Your Action Class

import { Action, ActionOptionsType } from "kist";

export interface YourActionOptions extends ActionOptionsType {
    input: string;
    output: string;
    // Add your options here
}

export class YourAction extends Action {
    validateOptions(options: ActionOptionsType): boolean {
        const opts = options as YourActionOptions;
        // Validate required options
        if (!opts.input || !opts.output) {
            throw new Error("YourAction requires input and output options");
        }
        return true;
    }

    async execute(options: ActionOptionsType): Promise<void> {
        const opts = options as YourActionOptions;
        this.logInfo("Starting YourAction...");

        try {
            // Your action logic here

            this.logInfo("YourAction completed successfully.");
        } catch (error) {
            this.logError("YourAction failed:", error);
            throw error;
        }
    }
}

2. Register Your Action

Update src/index.ts:

import { ActionPlugin } from "kist";
import { YourAction } from "./actions/YourAction.js";

const plugin: ActionPlugin = {
    version: "1.0.0",
    description: "Your action description",

    registerActions() {
        return {
            YourAction: YourAction,
        };
    },
};

export default plugin;
export { YourAction };

3. Write Tests

import { YourAction } from "./YourAction";

describe("YourAction", () => {
    let action: YourAction;

    beforeEach(() => {
        action = new YourAction();
    });

    it("should validate options correctly", () => {
        expect(
            action.validateOptions({
                input: "src",
                output: "dist",
            }),
        ).toBe(true);
    });

    it("should execute successfully", async () => {
        await action.execute({
            input: "./test/fixtures",
            output: "./test/output",
        });
    });
});

Testing Locally

Link to Test Project

# In your action directory
npm link

# In your test project
npm link @getkist/action-yourname

Use in kist.yml

pipeline:
    stages:
        - name: build
          steps:
              - name: your-step
                action: YourAction
                options:
                    input: ./src
                    output: ./dist

Publishing

1. Build and Test

npm run build
npm test

2. Version Bump

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

3. Publish to npm

npm login
npm publish --access public

Action Naming Conventions

Official Actions (kist organization)

• Name: @getkist/action-{name}
• Example: @getkist/action-sass, @getkist/action-typescript
• Repository: getkist/action-{name}

Community Actions

• Name: kist-action-{name} or @yourscope/kist-action-{name}
• Example: kist-action-markdown, @mycompany/kist-action-custom

Action Guidelines

Best Practices

1. Validation: Always validate options in validateOptions()
2. Logging: Use this.logInfo(), this.logWarn(), this.logError(), this.logDebug()
3. Error Handling: Wrap execution logic in try-catch blocks
4. TypeScript: Define clear interfaces for your options
5. Testing: Aim for >80% code coverage
6. Documentation: Provide clear README and inline documentation

Example Options Interface

export interface YourActionOptions extends ActionOptionsType {
    // Required options
    input: string;
    output: string;

    // Optional options with defaults
    verbose?: boolean;
    overwrite?: boolean;

    // Complex options
    config?: {
        minify?: boolean;
        sourceMap?: boolean;
    };
}

Examples

See the src/actions/ExampleAction.ts for a complete implementation example that demonstrates:

• Options validation
• Type safety with TypeScript
• Error handling
• Logging
• Async operations

Resources

• kist Documentation
• Plugin Development Guide
• Plugin Migration Guide
• Official Actions

Support

• Issues: GitHub Issues
• Discussions: kist Discussions

License

MIT © [Your Name]