declastruct-github 1.0.0

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "declastruct-github",
+  "author": "ehmpathy",
+  "description": "declarative control of GitHub constructs via declastruct - manage repos, branches, and protection rules",
+  "version": "1.0.0",
+  "repository": "ehmpathy/declastruct-github",
+  "homepage": "https://github.com/ehmpathy/declastruct-github",
+  "keywords": [
+    "github",
+    "declarative",
+    "declastruct",
+    "infrastructure-as-code",
+    "repository-management",
+    "branch-protection",
+    "github-api"
+  ],
+  "bugs": "https://github.com/ehmpathy/declastruct-github/issues",
+  "license": "MIT",
+  "main": "dist/contract/sdks/index.js",
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build:ts": "tsc -p ./tsconfig.build.json",
+    "commit:with-cli": "npx cz",
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "fix:format": "npm run fix:format:prettier",
+    "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
+    "build:clean": "rm dist/ -rf",
+    "build:compile": "tsc -p ./tsconfig.build.json",
+    "build": "npm run build:clean && npm run build:compile",
+    "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
+    "test:types": "tsc -p ./tsconfig.build.json --noEmit",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js",
+    "test:format": "npm run test:format:prettier",
+    "test:lint:deps": "npx depcheck -c ./depcheckrc.yml",
+    "test:lint:eslint": "eslint -c ./.eslintrc.js src/**/*.ts",
+    "test:lint": "npm run test:lint:eslint && npm run test:lint:deps",
+    "test:unit": "jest -c ./jest.unit.config.ts --forceExit --verbose --passWithNoTests $([ -z $THOROUGH ] && echo '--changedSince=main')",
+    "test:integration": "LOCALLY=true jest -c ./jest.integration.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "test:acceptance:locally": "npm run build && LOCALLY=true jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "test": "npm run test:commits && npm run test:types && npm run test:format && npm run test:lint && npm run test:unit && npm run test:integration && npm run test:acceptance:locally",
+    "test:acceptance": "npm run build && jest -c ./jest.acceptance.config.ts --forceExit --verbose --runInBand --passWithNoTests",
+    "prepush": "npm run test && npm run build",
+    "prepublish": "npm run build",
+    "preversion": "npm run prepush",
+    "postversion": "git push origin HEAD --tags --no-verify",
+    "postinstall": "[ -d .git ] && npm run prepare:husky || exit 0",
+    "prepare:husky": "npx husky install && chmod ug+x .husky/*"
+  },
+  "dependencies": {
+    "@ehmpathy/uni-time": "1.7.4",
+    "@octokit/rest": "^21.0.0",
+    "as-procedure": "1.1.1",
+    "declastruct": "1.1.5",
+    "domain-objects": "0.29.1",
+    "helpful-errors": "1.5.3",
+    "simple-in-memory-cache": "0.4.0",
+    "type-fns": "1.19.0",
+    "visualogic": "1.3.2",
+    "with-simple-cache": "0.15.1"
+  },
+  "devDependencies": {
+    "@babel/core": "7.28.5",
+    "@babel/preset-env": "7.28.5",
+    "@commitlint/cli": "19.3.0",
+    "@commitlint/config-conventional": "13.1.0",
+    "@octokit/types": "13.10.0",
+    "@trivago/prettier-plugin-sort-imports": "4.3.0",
+    "@tsconfig/node-lts-strictest": "18.12.1",
+    "@types/jest": "29.2.4",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
+    "babel-jest": "30.2.0",
+    "core-js": "3.26.1",
+    "cz-conventional-changelog": "3.3.0",
+    "declapract": "0.12.0",
+    "declapract-typescript-ehmpathy": "0.39.5",
+    "depcheck": "1.4.3",
+    "eslint": "8.56.0",
+    "eslint-config-airbnb-typescript": "18.0.0",
+    "eslint-config-prettier": "8.5.0",
+    "eslint-plugin-import": "2.26.0",
+    "eslint-plugin-prettier": "4.2.1",
+    "husky": "8.0.3",
+    "jest": "29.3.1",
+    "prettier": "2.8.1",
+    "rhachet": "1.12.1",
+    "rhachet-roles-ehmpathy": "1.8.0",
+    "simple-log-methods": "0.6.2",
+    "test-fns": "1.5.0",
+    "ts-jest": "29.4.5",
+    "ts-node": "10.9.2",
+    "typescript": "5.4.5"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,181 @@
+# declastruct-github
+
+![test](https://github.com/ehmpathy/declastruct-github/workflows/test/badge.svg)
+![publish](https://github.com/ehmpathy/declastruct-github/workflows/publish/badge.svg)
+
+Declarative control of Github resource constructs, via [declastruct](https://github.com/ehmpathy/declastruct).
+
+Declare the structures you want. Plan to see the changes required. Apply to make it so 🪄
+
+
+# install
+
+```sh
+npm install -s declastruct-github
+```
+
+# use via cli
+
+## example.1
+
+### wish ✨
+
+declare the resources you wish to have - and what state you wish them to be in
+
+```ts
+import { getDeclastructGithubProvider, DeclaredGithubRepo, DeclaredGithubRepoConfig } from 'declastruct-github';
+
+export const getProviders = async () => [
+  getDeclastructGithubProvider({
+    credentials: {
+      token: process.env.GITHUB_TOKEN,
+    }
+  })
+]
+
+export const getResources = async () => {
+  const repo = DeclaredGithubRepo.as({
+    name: 'super repo',
+  });
+  const repoConfig = DeclaredGithubRepoConfig.as({
+    repo: refByUnique(repo),
+
+    // for example, only allow squash merges
+    allowSquashMerge: true,
+    allowMergeCommit: false,
+    allowRebaseMerge: false,
+
+    // ... see the docs or types for other options
+  });
+
+  // ... add whatever resources you wish
+
+  return [
+    repo,
+    repoConfig,
+    // ... all the resources you wish for will go here
+  ],
+}
+```
+
+### plan 🔮
+
+plan how to achieve the wish of resources you've declared
+
+this will emit a plan that declares the changes required in order to fulfill the wish
+
+```sh
+npx declastruct plan --wish provision/github/resources.ts --output provision/github/.temp/plan.json
+```
+
+### apply 🪄
+
+apply the plan to fulfill the wish
+
+this will apply only the changes declared in the plan - and only if this plan is still applicable
+
+```sh
+npx declastruct apply --plan provision/github/.temp/plan.json
+```
+
+
+## example.2
+
+```ts
+export const getResources = async () => {
+  // declare the repo
+  const repo = DeclaredGithubRepo.as({
+    name: "your repo",
+  });
+
+  // declare the main branch
+  const branchMain = DeclaredGithubBranch.as({
+    repo: refByUnique(repo),
+    name: 'main',
+  })
+
+  // declare config for the repo
+  const repoConfig = DeclaredGithubRepoConfig.as({
+    // explicitly set the main branch
+    defaultBranch: refByUnique(branchMain),
+
+    // we only use issues; the rest is noise today
+    hasIssues: true,
+    hasProjects: false,
+    hasWiki: false,
+    hasDownloads: false,
+    isTemplate: false,
+
+    // only squash merges are allowed
+    allowSquashMerge: true,
+    allowMergeCommit: false, // but especially not merge merges. never merge merges
+    allowRebaseMerge: false,
+
+    // always cleanup after yourself
+    deleteBranchOnMerge: true,
+  });
+
+  // declare protection for that branch, too
+  const branchMainProtection = DeclaredGithubBranchProtection.as({
+    branch: refByUnique(branchMain),
+
+    enforceAdmins: true, // yes, even admins need to follow this (note: they can still take the time to go and change the settings temporarily for the exceptions)
+    allowsDeletions: false, // dont allow the `main` branch to be deleted
+    allowsForcePushes: false, // dont allow `main` branch to be force pushed to
+    requireLinearHistory: false, //  # no ugly merge commits, woo! 🎉
+
+    requiedStatusChecks: {
+      strict: true, // branch must be up to date. otherwise, we dont know if it will really pass once it is merged
+      contexts = [
+        "suite / install / npm",
+        "suite / test-commits",
+        "suite / test-types",
+        "suite / test-format",
+        "suite / test-lint",
+        "suite / test-unit",
+        "suite / test-integration",
+        "suite / test-acceptance-locally",
+        "pullreq-title" // "review / pullreq-title",
+      ]
+    }
+  })
+
+
+  return [
+    repo,
+    branchMain,
+    repoConfig,
+    branchMainProtection,
+  ]
+}
+```
+
+# use imperatively
+
+## resource=DeclaredGithubRepo
+
+### getRepos
+
+### getRepo
+
+### setRepo
+
+## resource=DeclaredGithubBranch
+
+### getBranches
+
+### getBranch
+
+### setBranch
+
+## resource=DeclaredGithubRepoConfig
+
+### getRepoConfig
+
+### setRepoConfig
+
+## resource=DeclaredGithubBranchProtection
+
+### getBranchProtection
+
+### setBranchProtection