@aliaksandarpratashchyk/kickcat 0.5.0

package/package.json

@@ -0,0 +1,91 @@
+{
+	"name": "@aliaksandarpratashchyk/kickcat",
+	"version": "0.5.0",
+	"description": "Infrastructure-as-code toolkit for GitHub repository automation. Includes reusable workflows, utilities, and a CLI to install workflow templates.",
+	"bin": {
+		"kickcat": "./dist/bundle.js"
+	},
+	"author": "Aliaksandar Pratashchyk <aliaksandarpratashchyk@gmail.com>",
+	"license": "MIT",
+	"keywords": [
+		"github-actions",
+		"workflows",
+		"automation",
+		"iac",
+		"cli",
+		"milestones",
+		"labels",
+		"projects",
+		"github",
+		"ci"
+	],
+	"files": [
+		"dist",
+		"templates",
+		"schemas",
+		"LICENSE",
+		"README.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/aliaksandarpratashchyk/kickcat.git"
+	},
+	"bugs": {
+		"url": "https://github.com/aliaksandarpratashchyk/kickcat/issues"
+	},
+	"homepage": "https://github.com/aliaksandarpratashchyk/kickcat#readme",
+	"scripts": {
+		"build": "webpack",
+		"e2e": "npm run build && jest --testPathIgnorePatterns src",
+		"test": "jest --testPathIgnorePatterns e2e > COVERAGE.md && coverage-badges-cli -s ./coverage/coverage-summary.json -o ./coverage.svg --label Coverage",
+		"format": "npx prettier . --write",
+		"lint": "cross-env ESLINT_ENV=cli npx eslint . --fix"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.0",
+		"@octokit/core": "^7.0.6",
+		"@octokit/types": "^16.0.0",
+		"@types/jest": "^30.0.0",
+		"@types/node": "^24.6.2",
+		"@types/underscore": "^1.13.0",
+		"coverage-badges-cli": "^2.2.0",
+		"cpx": "^1.2.1",
+		"cross-env": "^10.1.0",
+		"eslint": "^9.39.0",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-import-resolver-typescript": "^4.4.4",
+		"eslint-plugin-import-x": "^4.16.1",
+		"eslint-plugin-jest": "^29.0.1",
+		"eslint-plugin-perfectionist": "^4.15.1",
+		"fork-ts-checker-webpack-plugin": "^9.1.0",
+		"jest": "^30.1.3",
+		"memfs": "^4.51.0",
+		"prettier": "3.6.2",
+		"rimraf": "^6.1.0",
+		"terser-webpack-plugin": "^5.3.14",
+		"ts-jest": "^29.4.4",
+		"ts-loader": "^9.5.4",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.9.2",
+		"typescript-eslint": "^8.46.2",
+		"webpack": "^5.102.1",
+		"webpack-cli": "^6.0.1"
+	},
+	"dependencies": {
+		"@actions/core": "^1.10.1",
+		"@actions/github": "^6.0.0",
+		"@octokit/plugin-paginate-graphql": "^6.0.0",
+		"@octokit/plugin-paginate-rest": "^14.0.0",
+		"@octokit/plugin-rest-endpoint-methods": "^17.0.0",
+		"@octokit/rest": "^22.0.1",
+		"@types/js-yaml": "^4.0.9",
+		"ajv": "^8.17.1",
+		"commander": "^12.1.0",
+		"dotenv": "^17.2.3",
+		"octokit": "^5.0.5",
+		"reflect-metadata": "^0.2.2",
+		"tsyringe": "^4.10.0",
+		"underscore": "^1.13.7",
+		"yaml": "^2.4.1"
+	}
+}

package/schemas/issue.schema.yml

@@ -0,0 +1,165 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+title: 'GitHub Issue Schema'
+type: object
+required:
+  - title
+additionalProperties: false
+
+properties:
+  number:
+    order: 1
+    type: number
+    doNotSuggest: true
+    description: 'GitHub issue number assigned automatically.'
+    markdownDescription: |
+      **Internal GitHub issue number.**
+
+      - Added after first sync  
+      - Used for linking & referencing  
+      - Do not modify manually
+    x-kickcat-unique: true
+    x-kickcat-primary-key: true
+
+  title:
+    order: 2
+    type: string
+    description: 'Issue title.'
+    markdownDescription: |
+      **Issue title.**
+
+      Short, clear, and descriptive.
+
+      Example:
+      ```yaml
+      title: "Implement milestone synchronization"
+      ```
+    x-kickcat-new-unique: true
+
+  milestone:
+    order: 3
+    description: 'Milestone reference (number or key/title).'
+    markdownDescription: |
+      **Milestone reference for this issue.**
+
+      Accepts either:
+      - A **number** — GitHub milestone number  
+      - A **string** — milestone key or title  
+
+      Examples:
+      ```yaml
+      milestone: 3         # GitHub milestone #3
+      milestone: "[Seed] Milestone 1 – Setup"
+      milestone: "seed-1"
+      ```
+    oneOf:
+      - type: number
+      - type: string
+    x-kickcat-reference: milestone
+
+  labels:
+    order: 4
+    type: array
+    description: 'List of GitHub label names.'
+    markdownDescription: |
+      **Labels assigned to the issue.**
+
+      Must match defined labels in your label schema/files.
+
+      Example:
+      ```yaml
+      labels:
+        - "priority:high"
+        - "type:feature"
+      ```
+    items:
+      type: string
+    default: []
+    x-kickcat-reference: label
+
+  dependencies:
+    order: 5
+    type: array
+    description: 'List of dependent issues (string or number).'
+    markdownDescription: |
+      **Dependencies for this issue.**
+
+      Accepts:
+      - Issue numbers  
+      - Issue aliases (strings)
+
+      Examples:
+      ```yaml
+      dependencies:
+        - 12
+        - "issue-init"
+      ```
+    items:
+      oneOf:
+        - type: number
+        - type: string
+    default: []
+    x-kickcat-reference: issue
+
+  state:
+    order: 6
+    type: string
+    description: 'Issue state: open or closed.'
+    markdownDescription: |
+      **GitHub Issue State.**
+
+      Represents whether the issue is currently **open** or **closed**.
+
+      Allowed values:
+      - `open`
+      - `closed`
+
+      Matches GitHub API behavior (IssueState enum).
+    enum:
+      - open
+      - closed
+    enumDescriptions:
+      - 'Open issue'
+      - 'Closed issue'
+
+    markdownEnumDescriptions:
+      - |
+        **Open issue.**  
+        Active and not yet completed.
+      - |
+        **Closed issue.**  
+        Finished or archived.
+
+  description:
+    order: 8
+    type: string
+    format: textarea
+    description: 'Full issue description.'
+    markdownDescription: |
+      **Full issue description (Markdown supported).**
+
+      Supports:
+      - paragraphs  
+      - lists  
+      - code blocks  
+      - task lists  
+
+      Example:
+      ```md
+      ### Goal
+      Implement milestone sync.
+
+      ### Steps
+      - [ ] Parse YAML
+      - [ ] Compare with GitHub
+      - [ ] Update changed fields
+      ```
+
+defaultSnippets:
+  - label: 'Issue Template'
+    description: 'Insert a standard issue structure.'
+    body:
+      title: '$1'
+      milestone: '$2'
+      labels: []
+      dependencies: []
+      description: '$3'

package/schemas/label.schema.yml

@@ -0,0 +1,68 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+title: 'GitHub Label Schema'
+type: object
+required:
+  - name
+  - color
+additionalProperties: false
+
+properties:
+  name:
+    order: 1
+    type: string
+    description: 'Label name as it appears on GitHub.'
+    markdownDescription: |
+      **Label name** displayed on GitHub.
+
+      Examples:
+      - `priority:high`
+      - `type:feature`
+      - `scope:core`
+
+      This name must be **unique** per repository.
+    x-kickcat-unique: true
+    x-kickcat-primary-key: true
+
+  color:
+    order: 2
+    type: string
+    pattern: '^[0-9a-fA-F]{6}$'
+    description: 'Hex color (6 characters, without #).'
+    markdownDescription: |
+      **Label color in hex format**.
+
+      Must be a 6-character hex code:
+      - lowercase or uppercase
+      - must **not** include `#`
+
+      Examples:
+      ```yaml
+      color: "d73a4a"   # red
+      color: "1d76db"   # blue
+      color: "0e8a16"   # green
+      ```
+
+  description:
+    order: 3
+    type: string
+    format: textarea
+    description: 'Full label description.'
+    markdownDescription: |
+      **Full description of the label.**
+
+      This appears on GitHub when hovering over the label.
+      Supports Markdown formatting.
+
+      Example:
+      ```md
+      Must be fixed as soon as possible.
+      Blocks releases.
+      ```
+
+defaultSnippets:
+  - label: 'Label Template'
+    description: 'Insert a standard GitHub label structure.'
+    body:
+      name: '$1'
+      color: '$2'
+      description: '$3'

package/schemas/milestone.schema.yml

@@ -0,0 +1,109 @@
+$schema: 'http://json-schema.org/draft-07/schema#'
+title: 'GitHub Milestone Schema'
+type: object
+required:
+  - title
+additionalProperties: false
+
+properties:
+  number:
+    doNotSuggest: true
+    order: 1
+    type: integer
+    description: 'GitHub milestone number assigned by GitHub.'
+    markdownDescription: |
+      **Internal GitHub milestone number.**
+
+      - Automatically added after creation  
+      - Used as a stable reference for updates  
+      - Do not edit manually
+    x-kickcat-unique: true
+    x-kickcat-primary-key: true
+
+  title:
+    order: 2
+    type: string
+    description: 'Milestone title.'
+    markdownDescription: |
+      **Milestone title shown on GitHub.**
+
+      Tip: Titles often include a key prefix in square brackets,  
+      e.g. `[Seed] Milestone 1 – Preparation`.
+
+      This acts as the *unique key* for matching milestones between  
+      YAML files and GitHub during syncing.
+    x-kickcat-unique: true
+
+  dueDate:
+    order: 3
+    type: string
+    format: date
+    description: 'Due date in YYYY-MM-DD.'
+    markdownDescription: |
+      **Optional milestone due date.**
+
+      Use ISO format: `YYYY-MM-DD`.
+
+      Example:
+      ```yaml
+      dueDate: "2025-05-17"
+      ```
+
+  state:
+    order: 4
+    type: string
+    enum:
+      - open
+      - closed
+    description: 'Milestone state.'
+    markdownDescription: |
+      **Milestone state.**
+
+      - `open` – displayed as active on GitHub  
+      - `closed` – milestone is finished  
+
+      Your sync workflow will preserve or update this based on configuration.
+
+    enumDescriptions:
+      - 'Open milestone'
+      - 'Closed milestone'
+
+    markdownEnumDescriptions:
+      - |
+        **Open milestone.**  
+        Active and not yet completed.
+      - |
+        **Closed milestone.**  
+        Finished or archived.
+
+  description:
+    order: 5
+    type: string
+    format: textarea
+    description: 'Full milestone description.'
+    markdownDescription: |
+      **Full milestone description.**
+
+      Supports Markdown formatting:
+
+      - lists  
+      - bold/italic  
+      - links  
+      - code blocks  
+
+      Example:
+      ```md
+      ### Goal
+      Complete initial project setup.
+
+      ### Outcomes
+      - Repo ready
+      - CI configured
+      ```
+
+defaultSnippets:
+  - label: 'Milestone Template'
+    description: 'Insert a standard milestone structure.'
+    body:
+      title: '$1'
+      description: '$2'

package/templates/workflows/kickcat-pull-issue.yml

@@ -0,0 +1,72 @@
+# Keep KickCat issues in sync with GitHub issue events
+name: kickcat-sync-issue
+
+on:
+  issues:
+    types: [opened, edited, reopened, closed, deleted]
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    env:
+      KICKCAT_LOCAL_STORAGE: .github
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Sync issue into repository storage
+        env:
+          ACTION: ${{ github.event.action }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${ISSUE_NUMBER:-}" ]; then
+            echo "Issue number is missing; skipping."
+            exit 0
+          fi
+
+          case "${ACTION}" in
+            opened|edited|reopened|closed)
+              npx @aliaksandarpratashchyk/kickcat entity pull --of=issue --key=number --value="${ISSUE_NUMBER}"
+              ;;
+            deleted)
+              npx @aliaksandarpratashchyk/kickcat entity delete --of=issue --key=number --value="${ISSUE_NUMBER}"
+              ;;
+            *)
+              echo "Issue action ${ACTION} not handled; skipping."
+              ;;
+          esac
+
+      - name: Commit changes
+        id: commit
+        env:
+          ACTION: ${{ github.event.action }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- .github; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github
+          git commit -m "chore: sync issue #${ISSUE_NUMBER} (${ACTION})"
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push changes
+        if: steps.commit.outputs.has_changes == 'true'
+        run: git push

package/templates/workflows/kickcat-pull-label.yml

@@ -0,0 +1,72 @@
+# Keep KickCat labels in sync with GitHub label events
+name: kickcat-sync-label
+
+on:
+  label:
+    types: [created, edited, deleted]
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    env:
+      KICKCAT_LOCAL_STORAGE: .github
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Sync label into repository storage
+        env:
+          ACTION: ${{ github.event.action }}
+          LABEL_NAME: ${{ github.event.label.name }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${LABEL_NAME:-}" ]; then
+            echo "Label name is missing; skipping."
+            exit 0
+          fi
+
+          case "${ACTION}" in
+            created|edited)
+              npx @aliaksandarpratashchyk/kickcat entity pull --of=label --key=name --value="${LABEL_NAME}"
+              ;;
+            deleted)
+              npx @aliaksandarpratashchyk/kickcat entity delete --of=label --key=name --value="${LABEL_NAME}"
+              ;;
+            *)
+              echo "Label action ${ACTION} not handled; skipping."
+              ;;
+          esac
+
+      - name: Commit changes
+        id: commit
+        env:
+          ACTION: ${{ github.event.action }}
+          LABEL_NAME: ${{ github.event.label.name }}
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- .github; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github
+          git commit -m "chore: sync label ${LABEL_NAME} (${ACTION})"
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push changes
+        if: steps.commit.outputs.has_changes == 'true'
+        run: git push

package/templates/workflows/kickcat-pull-milestone.yml

@@ -0,0 +1,70 @@
+# Keep KickCat milestones in sync with GitHub milestone events
+name: kickcat-pull-milestone
+
+on:
+  milestone:
+    types: [created, opened, edited, closed, deleted]
+
+permissions:
+  contents: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Sync milestone into repository storage
+        env:
+          ACTION: ${{ github.event.action }}
+          MILESTONE_NUMBER: ${{ github.event.milestone.number }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${MILESTONE_NUMBER:-}" ]; then
+            echo "Milestone number is missing; skipping."
+            exit 0
+          fi
+
+          case "${ACTION}" in
+            created|opened|edited|closed)
+              npx @aliaksandarpratashchyk/kickcat entity pull --of=milestone --key=number --value="${MILESTONE_NUMBER}"
+              ;;
+            deleted)
+              npx @aliaksandarpratashchyk/kickcat entity delete --of=milestone --key=number --value="${MILESTONE_NUMBER}"
+              ;;
+            *)
+              echo "Milestone action ${ACTION} not handled; skipping."
+              ;;
+          esac
+
+      - name: Commit changes
+        id: commit
+        env:
+          ACTION: ${{ github.event.action }}
+          MILESTONE_NUMBER: ${{ github.event.milestone.number }}
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- .github; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github
+          git commit -m "chore: sync milestone #${MILESTONE_NUMBER} (${ACTION})"
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push changes
+        if: steps.commit.outputs.has_changes == 'true'
+        run: git push

package/templates/workflows/kickcat-push-all.yml

@@ -0,0 +1,59 @@
+# Push all KickCat entities from local storage to GitHub
+name: kickcat-push-all
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - '.github/**/*.yml'
+      - 'schemas/**'
+      - 'templates/**'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  push-all:
+    if: "${{ !(github.event_name == 'push' && (github.actor == 'github-actions[bot]' || startsWith(github.event.head_commit.message || '', 'chore: sync '))) }}"
+    runs-on: ubuntu-latest    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Push entities to GitHub
+        env:                  
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          npx @aliaksandarpratashchyk/kickcat entity push all --log-level=info
+
+      - name: Commit changes
+        id: commit
+        run: |
+          set -euo pipefail
+
+          if git diff --quiet -- .github; then
+            echo "has_changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .github
+          git commit -m "chore: push all KickCat entities"
+          echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+      - name: Push changes
+        if: steps.commit.outputs.has_changes == 'true'
+        run: git push