@justanarthur/just-github-actions-n-workflows-cli 0.0.0-beta.5

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@justanarthur/just-github-actions-n-workflows-cli",
+  "version": "0.0.0-beta.5",
+  "description": "Release automation toolkit — version bumping, npm publishing, docker publishing, VPS deployment via GitHub Actions composite actions",
+  "type": "module",
+  "bin": {
+    "just-github-actions-n-workflows": "./src/index.ts"
+  },
+  "scripts": {
+    "publish": "bun publish --access public"
+  },
+  "files": [
+    "src/**/*.ts",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/justAnArthur/just-github-actions-n-workflows"
+  },
+  "dependencies": {
+    "@oclif/core": "^4",
+    "@inquirer/prompts": "^7"
+  },
+  "oclif": {
+    "commands": "./src/commands",
+    "default": "init"
+  },
+  "properties": {
+    "gitCommitScopeRelatedNames": "cli"
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,265 @@
+import { Args, Command, Flags, ux } from "@oclif/core"
+import { checkbox, select } from "@inquirer/prompts"
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import {
+  REPO,
+  enrichWorkflows,
+  fetchTags,
+  fetchWorkflowContent,
+  fetchWorkflowList,
+  type WorkflowEntry,
+} from "../github.js"
+
+export default class Init extends Command {
+  static override description = "Scaffold workflow files into .github/workflows/ of the current repo"
+
+  static override examples = [
+    "<%= config.bin %> init",
+    "<%= config.bin %> init bump-version",
+    "<%= config.bin %> init --ref v1.0.0",
+    "<%= config.bin %> init --list",
+    "<%= config.bin %> init --yes --force",
+  ]
+
+  static override args = {
+    workflows: Args.string({
+      description: "Specific workflow names to install (space-separated)",
+      required: false,
+    }),
+  }
+
+  static override strict = false
+
+  static override flags = {
+    list: Flags.boolean({
+      char: "l",
+      description: "Show available workflows",
+      default: false,
+    }),
+    force: Flags.boolean({
+      char: "f",
+      description: "Overwrite existing workflow files",
+      default: false,
+    }),
+    yes: Flags.boolean({
+      char: "y",
+      description: "Skip interactive prompts, install all workflows",
+      default: false,
+    }),
+    ref: Flags.string({
+      description: "Git ref to fetch from (branch, tag, or sha)",
+      default: "main",
+    }),
+  }
+
+  async run(): Promise<void> {
+    const { argv, flags } = await this.parse(Init)
+    const positional = argv as string[]
+
+    // --- list mode ---
+
+    if (flags.list) {
+      await this.listWorkflows(flags.ref)
+      return
+    }
+
+    // --- interactive / install mode ---
+
+    this.log()
+    this.log(ux.colorize("bold", "  just-github-actions-n-workflows"))
+    this.log(ux.colorize("dim", "  release automation toolkit\n"))
+
+    const ref = await this.resolveRef(flags, positional)
+    const selected = await this.selectWorkflows(ref, flags, positional)
+
+    if (selected.length === 0) {
+      this.log(ux.colorize("yellow", "\n  no workflows selected — nothing to do.\n"))
+      return
+    }
+
+    const { created, skipped } = await this.installWorkflows(selected, ref, flags)
+
+    this.log(`\n  done — ${ux.colorize("green", `${created} created`)}, ${skipped} skipped\n`)
+
+    this.printSecretsReminder(selected)
+    this.printNextSteps(created, selected)
+  }
+
+  // ── step 1: resolve ref ────────────────────────────────
+
+  private async resolveRef(
+    flags: { ref: string; yes: boolean },
+    positional: string[]
+  ): Promise<string> {
+    if (flags.ref !== "main" || positional.length > 0 || flags.yes) {
+      return flags.ref
+    }
+
+    this.log(ux.colorize("bold", "  step 1 — select version\n"))
+
+    const tags = await fetchTags()
+
+    if (tags.length === 0) return "main"
+
+    const choices = [
+      { name: `main ${ux.colorize("dim", "(latest)")}`, value: "main" },
+      ...tags.slice(0, 9).map((tag) => ({ name: tag, value: tag })),
+    ]
+
+    const ref = await select({
+      message: "Pick a version",
+      choices,
+      default: "main",
+    })
+
+    this.log(ux.colorize("green", `\n  → using ${ref}\n`))
+    return ref
+  }
+
+  // ── step 2: select workflows ───────────────────────────
+
+  private async selectWorkflows(
+    ref: string,
+    flags: { yes: boolean },
+    positional: string[]
+  ): Promise<WorkflowEntry[]> {
+    let available = await fetchWorkflowList(ref)
+    available = await enrichWorkflows(available, ref)
+
+    if (positional.length > 0) {
+      return positional.map((name) => {
+        const key = name.replace(/\.yml$/, "")
+        const wf = available.find((w) => w.name === key)
+        if (!wf) {
+          this.error(`Unknown workflow "${name}". Available: ${available.map((w) => w.name).join(", ")}`)
+        }
+        return wf!
+      })
+    }
+
+    if (flags.yes) return available
+
+    this.log(ux.colorize("bold", "  step 2 — select workflows\n"))
+
+    const selected = await checkbox({
+      message: "Select workflows to install",
+      choices: available.map((wf) => {
+        const secretNames = wf.secrets?.map((s) => s.split(/\s+[—–]\s*/)[0]).join(", ")
+        const hint = [
+          wf.description,
+          secretNames ? `requires: ${secretNames}` : null,
+        ].filter(Boolean).join(" · ")
+
+        return {
+          name: `${wf.name.padEnd(26)} ${ux.colorize("dim", hint || wf.file)}`,
+          value: wf.name,
+          checked: true,
+        }
+      }),
+    })
+
+    return available.filter((w) => selected.includes(w.name))
+  }
+
+  // ── step 3: install ────────────────────────────────────
+
+  private async installWorkflows(
+    selected: WorkflowEntry[],
+    ref: string,
+    flags: { force: boolean; yes: boolean }
+  ): Promise<{ created: number; skipped: number }> {
+    const targetDir = join(process.cwd(), ".github", "workflows")
+    mkdirSync(targetDir, { recursive: true })
+
+    if (!flags.yes) {
+      this.log(ux.colorize("bold", "  step 3 — install\n"))
+    }
+
+    this.log(ux.colorize("dim", `  fetching from ${REPO} @ ${ref}\n`))
+
+    let created = 0
+    let skipped = 0
+
+    for (const workflow of selected) {
+      const targetPath = join(targetDir, workflow.file)
+
+      if (!flags.force && existsSync(targetPath)) {
+        this.log(`  ${ux.colorize("yellow", "skip")}    ${workflow.file} ${ux.colorize("dim", "(already exists, use --force)")}`)
+        skipped++
+        continue
+      }
+
+      try {
+        const content = await fetchWorkflowContent(workflow.file, ref)
+        writeFileSync(targetPath, content, "utf-8")
+        this.log(`  ${ux.colorize("green", "create")}  .github/workflows/${workflow.file}`)
+        created++
+      } catch (error: any) {
+        this.log(`  ${ux.colorize("red", "error")}   ${workflow.file}: ${error.message}`)
+      }
+    }
+
+    return { created, skipped }
+  }
+
+  // ── step 4: secrets reminder ───────────────────────────
+
+  private printSecretsReminder(selected: WorkflowEntry[]): void {
+    const allSecrets = new Map<string, string>()
+    for (const wf of selected) {
+      for (const s of wf.secrets || []) {
+        const [name, ...descParts] = s.split(/\s+[—–]\s*/)
+        if (name && !allSecrets.has(name.trim())) {
+          allSecrets.set(name.trim(), descParts.join(" — ").trim())
+        }
+      }
+    }
+
+    if (allSecrets.size === 0) return
+
+    this.log(ux.colorize("bold", "  required secrets:\n"))
+    for (const [name, desc] of allSecrets) {
+      this.log(`  • ${ux.colorize("cyan", name.padEnd(18))} ${ux.colorize("dim", desc)}`)
+    }
+    this.log(ux.colorize("dim", `\n  set these in your repo → Settings → Secrets → Actions\n`))
+  }
+
+  // ── next steps ─────────────────────────────────────────
+
+  private printNextSteps(created: number, selected: WorkflowEntry[]): void {
+    if (created === 0) return
+
+    const hasSecrets = selected.some((w) => w.secrets && w.secrets.length > 0)
+
+    this.log(ux.colorize("bold", "  next steps:\n"))
+    this.log(`  1. ${hasSecrets ? "set the secrets listed above" : "set the GH_TOKEN secret in your repo settings"}`)
+    this.log(`  2. adjust push.branches / push.tags triggers for your repo`)
+    this.log(`  3. commit and push:`)
+    this.log(ux.colorize("dim", `     git add .github/ && git commit -m "ci: add workflows" && git push`))
+    this.log()
+  }
+
+  // ── list mode ──────────────────────────────────────────
+
+  private async listWorkflows(ref: string): Promise<void> {
+    const workflows = await enrichWorkflows(await fetchWorkflowList(ref), ref)
+
+    this.log(`\n${ux.colorize("bold", "available workflows")} ${ux.colorize("dim", `(${REPO} @ ${ref})`)}\n`)
+
+    for (const w of workflows) {
+      this.log(`  ${ux.colorize("cyan", w.name.padEnd(28))} → .github/workflows/${w.file}`)
+      if (w.description) {
+        this.log(`  ${"".padEnd(28)}   ${ux.colorize("dim", w.description)}`)
+      }
+      if (w.secrets?.length) {
+        const names = w.secrets.map((s) => s.split(/\s+[—–]\s*/)[0]).join(", ")
+        this.log(`  ${"".padEnd(28)}   ${ux.colorize("dim", `secrets: ${names}`)}`)
+      }
+      this.log()
+    }
+  }
+}
+
+

package/src/github.ts

@@ -0,0 +1,113 @@
+import pkg from "../package.json"
+
+const REPO = pkg.repository.url
+  .replace(/^https?:\/\/github\.com\//, "")
+  .replace(/\.git$/, "")
+
+const API_BASE = `https://api.github.com/repos/${REPO}`
+const RAW_BASE = `https://raw.githubusercontent.com/${REPO}`
+
+export { REPO }
+
+// --- types ---
+
+export type WorkflowEntry = {
+  name: string
+  file: string
+  description?: string
+  secrets?: string[]
+}
+
+// --- parse workflow header ---
+// extracts description and required secrets from the yaml header comment block.
+
+export function parseWorkflowHeader(content: string): { description: string; secrets: string[] } {
+  const lines = content.split("\n")
+  let description = ""
+  const secrets: string[] = []
+  let inHeader = false
+
+  for (const line of lines) {
+    if (line.startsWith("# ---")) {
+      if (inHeader) break
+      inHeader = true
+      continue
+    }
+    if (!inHeader) continue
+    if (!line.startsWith("#")) break
+
+    const text = line.replace(/^#\s?/, "").trim()
+
+    if (/^required secrets:/i.test(text)) continue
+    if (/^\w+\s+[—–]/.test(text)) {
+      secrets.push(text)
+      continue
+    }
+
+    if (!description && text && !/^copy this|^can also|^actions used|^paste this|^this one/i.test(text)) {
+      description = text
+    }
+  }
+
+  return { description, secrets }
+}
+
+// --- api ---
+
+export async function fetchTags(): Promise<string[]> {
+  const url = `${API_BASE}/tags?per_page=20`
+  const res = await fetch(url, {
+    headers: { Accept: "application/vnd.github.v3+json" }
+  })
+  if (!res.ok) return []
+  const tags: any[] = await res.json()
+  return tags.map((t) => t.name)
+}
+
+export async function fetchWorkflowList(gitRef: string): Promise<WorkflowEntry[]> {
+  const url = `${API_BASE}/contents/workflows?ref=${gitRef}`
+  const res = await fetch(url, {
+    headers: { Accept: "application/vnd.github.v3+json" }
+  })
+
+  if (!res.ok) {
+    throw new Error(`failed to list workflows from ${REPO} @ ${gitRef} (${res.status})`)
+  }
+
+  const entries: any[] = await res.json()
+
+  return entries
+    .filter((e) => e.type === "file" && e.name.endsWith(".yml"))
+    .map((e) => ({
+      name: e.name.replace(/\.yml$/, ""),
+      file: e.name
+    }))
+}
+
+export async function fetchWorkflowContent(file: string, gitRef: string): Promise<string> {
+  const url = `${RAW_BASE}/${gitRef}/workflows/${file}`
+  const res = await fetch(url)
+
+  if (!res.ok) {
+    throw new Error(`failed to fetch workflows/${file} from ${REPO} @ ${gitRef} (${res.status})`)
+  }
+
+  return await res.text()
+}
+
+export async function enrichWorkflows(workflows: WorkflowEntry[], gitRef: string): Promise<WorkflowEntry[]> {
+  const enriched: WorkflowEntry[] = []
+
+  for (const wf of workflows) {
+    try {
+      const content = await fetchWorkflowContent(wf.file, gitRef)
+      const { description, secrets } = parseWorkflowHeader(content)
+      enriched.push({ ...wf, description, secrets })
+    } catch {
+      enriched.push(wf)
+    }
+  }
+
+  return enriched
+}
+

package/src/index.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { execute } from "@oclif/core"
+
+await execute({ dir: import.meta.url })
+

package/src/init.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// This file has been replaced by:
+//   src/index.ts          — oclif entry point
+//   src/commands/init.ts   — init command
+//   src/github.ts          — github api helpers
+//
+// You can safely delete this file.