Add CLI tool (#103)

.github/workflows/ci.yml

@@ -58,8 +58,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup-deno-with-cache
-      - id: test
-        run: deno test
+      - run: deno test
+      - name: CLI somke test
+        run: |
+          RUN_URL=$(gh run list -L 1 -w release --json url --jq .[].url)
+          deno run --allow-net --allow-write cli.ts -t "${GITHUB_TOKEN}" -o output.md $RUN_URL
+          cat output.md
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   run_self:
     runs-on: ubuntu-latest

README.md

@@ -2,7 +2,10 @@
 
 An Action shows timeline of a GitHub Action workflow in the run summary page.
 
-`actions-timeline` is a tool that allows developers to visualize the sequence of jobs and steps that occur during a GitHub Actions workflow. By examining the timeline, you can quickly identify any issues or bottlenecks in your workflow, and make adjustments as needed to improve performance and efficiency.
+`actions-timeline` is a tool that allows developers to visualize the sequence of
+jobs and steps that occur during a GitHub Actions workflow. By examining the
+timeline, you can quickly identify any issues or bottlenecks in your workflow,
+and make adjustments as needed to improve performance and efficiency.
 
 ![Sample screenshot](https://user-images.githubusercontent.com/1324862/268660777-5ee9fffd-6ef7-4960-9632-3589cb7138e1.png)
 
@@ -42,19 +45,31 @@ jobs:
 
 ## How it works
 
-`actions-timeline` fetches the jobs and steps of the workflow run from the GitHub API, and then generates a timeline with [mermaid gantt diagrams](https://mermaid.js.org/syntax/gantt.html). Thanks to the GitHub flavored markdown that can visualize mermaid diagrams, the timeline is displayed in the run summary page.
+`actions-timeline` fetches the jobs and steps of the workflow run from the
+GitHub API, and then generates a timeline with
+[mermaid gantt diagrams](https://mermaid.js.org/syntax/gantt.html). Thanks to
+the GitHub flavored markdown that can visualize mermaid diagrams, the timeline
+is displayed in the run summary page.
 
-This action is run on post-processing of the job, so you should register this action before your build step. If you register this action after your build step, the timeline will not include other post-processing steps.
+This action is run on post-processing of the job, so you should register this
+action before your build step. If you register this action after your build
+step, the timeline will not include other post-processing steps.
 
 ## Support GHES
 
-`actions-timeline` can also work on GitHub Enterprise Server(GHES). It needs `GITHUB_API_URL` environment variable to access your GHES. Thanks to GitHub Actions, it sets [default environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables) so you do not need to make any code changes.
+`actions-timeline` can also work on GitHub Enterprise Server(GHES). It needs
+`GITHUB_API_URL` environment variable to access your GHES. Thanks to GitHub
+Actions, it sets
+[default environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables)
+so you do not need to make any code changes.
 
 ## Known issues
 
 ### In some cases, the workflow requires `actions:read' permission.
 
-Sometimes the `actions:read' permission is needed in the workflow to fetch workflow jobs and steps. If you see the following error, you need to add the`actions:read' permission to your workflow.
+Sometimes the
+`actions:read' permission is needed in the workflow to fetch workflow jobs and steps. If you see the following error, you need to add the`actions:read'
+permission to your workflow.
 
 ```yaml
 jobs:
@@ -68,14 +83,55 @@ jobs:
 
 ### 'Waiting for a runner' step is not supported < GHES v3.9
 
-GET `workflow_job` API response does not contain `created_at` field in [GHES v3.8](https://docs.github.com/en/[email protected]/rest/actions/workflow-jobs#get-a-job-for-a-workflow-run), it is added from [GHES v3.9](https://docs.github.com/en/[email protected]/rest/actions/workflow-jobs?apiVersion=2022-11-28). So it is not possible to calculate the elapsed time the runner is waiting for a job, `actions-timeline` inserts a dummy step instead.
+GET `workflow_job` API response does not contain `created_at` field in
+[GHES v3.8](https://docs.github.com/en/[email protected]/rest/actions/workflow-jobs#get-a-job-for-a-workflow-run),
+it is added from
+[GHES v3.9](https://docs.github.com/en/[email protected]/rest/actions/workflow-jobs?apiVersion=2022-11-28).
+So it is not possible to calculate the elapsed time the runner is waiting for a
+job, `actions-timeline` inserts a dummy step instead.
 
 # Similar works
 
 - https://github.com/Kesin11/github_actions_otel_trace
 - https://github.com/inception-health/otel-export-trace-action
 - https://github.com/runforesight/workflow-telemetry-action
 
+# CLI tool
+
+`actions-timeline` is also available as a CLI tool. You can use it with
+`deno run` command.
+
+```bash
+deno run --allow-net --allow-write \
+  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
+  https://github.com/Kesin11/actions-timeline/actions/runs/8021493760/attempts/1 \
+  -t $(gh auth token) \
+  -o output.md
+
+# Fetch latest attempt if ommit attempts
+deno run --allow-net --allow-write \
+  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
+  https://github.com/Kesin11/actions-timeline/actions/runs/8021493760/ \
+  -t $(gh auth token) \
+  -o output.md
+
+# GHES
+deno run --allow-net --allow-write \
+  https://raw.githubusercontent.com/Kesin11/actions-timeline/main/cli.ts \
+  https://YOUR_ENTERPRISE_HOST/OWNER/REPO/actions/runs/RUN_ID/attempts/1 \
+  -t $(gh auth token -h YOUR_ENTERPRISE_HOST) \
+  -o output.md
+```
+
+`cli.ts` just outputs the markdown to file or STDOUT, so you have to use other
+tools to visualize mermaid diagrams.
+
+- Online editor:
+  [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/)
+- VSCode extension:
+  [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
+- Local terminal: [mermaid-cli](https://github.com/mermaid-js/mermaid-cli)
+
 # DEVELOPMENT
 
 ## Setup

cli.ts

@@ -0,0 +1,58 @@
+import { Command } from "https://deno.land/x/[email protected]/command/mod.ts";
+import { createMermaid } from "./src/workflow_gantt.ts";
+import {
+  createOctokitForCli,
+  fetchWorkflow,
+  fetchWorkflowLatestAttempt,
+  fetchWorkflowRunJobs,
+} from "./src/github.ts";
+import { parseWorkflowRunUrl } from "./src/github.ts";
+
+const { options, args } = await new Command()
+  .name("actions-timeline-cli")
+  .description("Command line tool of actions-timeline")
+  .option("-t, --token <token:string>", "GitHub token. ex: $(gh auth token)")
+  .option(
+    "-o, --output <output:file>",
+    "Output md file path. If not set output to STDOUT. ex: output.md",
+  )
+  .arguments("<url:string>")
+  .parse(Deno.args);
+
+const url = args[0];
+const runUrl = parseWorkflowRunUrl(url);
+
+const octokit = createOctokitForCli({
+  token: options.token,
+  origin: runUrl.origin,
+});
+
+const runAttempt = runUrl.runAttempt ??
+  await fetchWorkflowLatestAttempt(
+    octokit,
+    runUrl.owner,
+    runUrl.repo,
+    runUrl.runId,
+  );
+
+const workflow = await fetchWorkflow(
+  octokit,
+  runUrl.owner,
+  runUrl.repo,
+  runUrl.runId,
+  runAttempt,
+);
+const workflowJobs = await fetchWorkflowRunJobs(
+  octokit,
+  runUrl.owner,
+  runUrl.repo,
+  runUrl.runId,
+  runAttempt,
+);
+const gantt = createMermaid(workflow, workflowJobs);
+
+if (options.output) {
+  await Deno.writeTextFile(options.output, gantt);
+} else {
+  console.log(gantt);
+}

deno.jsonc

@@ -1,6 +1,5 @@
 {
   "tasks": {
-    "setup:githooks": "git config --local core.hooksPath .githooks",
     "bundle": "deno run -A scripts/build.ts",
     "bundle:commit": "deno task bundle && git add -u dist && git commit -m 'deno task bundle'"
   },