📝 Update docs + usage

Author: ebullient

.github/actions/count-votes/action.yml

@@ -103,21 +103,22 @@ runs:
         markdown=
         if [[ -n "${CREATE_MD}" ]]; then
           markdown="--md=\"${MD_DIR}\""
-          mkdir -p ${MD_DIR}
         fi
 
         # collect vote results from recently updated issues, prs, discussions
         node vote-record-actions/dist/votes.js "${TARGET_DIR}" ${repos} ${remove} ${markdown} ${bot}
 
         git add -A -- "${TARGET_DIR}"
         if [[ -n "${CREATE_MD}" ]]; then
+          # stage markdown results
           git add -A -- "${MD_DIR}"
         fi
 
         # Regenerate the index if that value is true
+        # index will reference markdown results (relative paths)
         if [ -n "${CREATE_INDEX}" ]; then
-          mkdir -p $(dirname ${MD_DIR})
           node vote-record-actions/dist/genIndex.js "${TARGET_DIR}" "${MD_DIR}" "${INDEX_FILE}"
+
           # Stage the index.
           git add -A -- "${INDEX_FILE}"
         fi

README.md

@@ -1,24 +1,57 @@
 # Vote Record Actions
 
-Common TS Actions that parse/munge vote data stored in issue comments
-care of the [haus-rules-bot](https://github.com/commonhaus/automation).
+Library/Utility to parse/munge vote data stored in issue comments care of the [haus-rules-bot](https://github.com/commonhaus/automation).
+
+For version in the examples below, use `main` or a published release
+
+## Count votes action
+
+Fine grained action that looks for comments from the specified bot, and creates vote records based on the data in those comments.
+It can also (optionally) create a file that lists outstanding/open votes.
+
+```yaml
+      - name: Count votes
+        id: count_votes
+        uses: commonhaus/vote-record-actions/.github/actions/count-votes@<version>
+        with:
+          repositories: "commonhaus/foundation"
+          target_dir: "site/_generated/votes"
+          branch: "main"
+```
+
+## Receive votes workflow
+
+Common workflow for dealing with pushed updates related to votes.
+This workflow uses the count-votes action
+
+```yaml
+  test_votes:
+    uses: commonhaus/vote-record-actions/.github/workflows/receive-votes.yml@<version>
+    with:
+      repositories: "commonhaus-test/automation-test"
+      vote_comment_bot: "commonhaus-test-bot[bot]"
+      removeTags: "notice"
+      target_dir: "votes/raw"
+      markdown_dir: "votes/results"
+      index_file: "votes/README.md"
+    secrets: inherit
+```
+
+For version, use `main` or a published release
+
+## Directly with node/TS
+
+"Usage: node vote-record-actions/dist/votes.js [all|recent] jsonDir [--repos=org/repo1,org/repo2] [--md=mdDir] [--removeTag=tag1] --bot=bot-comment-login"
 
 ```bash
 $ gh repo clone commonhaus/vote-record-actions -- --depth=1
 $ cd vote-record-actions
 $ npm ci
+$ npm build
 
 # Fetch the results from the bot comment on an issue
-$ npm run votes ../votes IC_kwDOKRPTI86LlGLV
+$ node ./dist/votes.js "~/votes/raw" --repos="commonhaus/foundation" --md="~/votes/results"
 
-# Update an index that summarizes outstanding actions
-$ npm run index ../votes
+# Update an index that summarizes outstanding actions (references markdown results)
+$ node ./dist/genIndex.js "~/votes/raw" "~/votes/results" "~/votes/README.md"
 ```
-
-## Reusable workflows
-
-Common workflows for dealing with pushed updates related to votes.
-
-## Reusable actions
-
-Composite actions.

src/genIndex.ts

@@ -6,7 +6,7 @@ import { findFiles, makePathRelativeTo } from "./lib/voteRecords";
 
 const scriptRoot = dirname(import.meta.dirname);
 
-const usage = "Usage: npm run genIndex jsonDir mdDir indexFile";
+const usage = "Usage: node ./dist/genIndex.js jsonDir mdDir indexFile";
 
 const args = process.argv.slice(2);
 if (args.length < 3) {

src/votes.ts

@@ -1,21 +1,18 @@
+import { existsSync, mkdirSync } from "node:fs";
 import type { VoteConfig } from "./@types";
 import { recordVote } from "./lib/voteRecords";
 import { queryVotes } from "./lib/voteResults";
 
 const usage =
-    "Usage: npm run votes [all|recent] jsonDir [--repos=org/repo1,org/repo2] [--md=mdDir] [--removeTag=tag1]";
+    "Usage: node ./dist/votes.js [all|recent] jsonDir [--repos=org/repo1,org/repo2] [--md=mdDir] [--removeTag=tag1]";
 
 const config: VoteConfig = {
     bot: "haus-rules-bot[bot]",
     options: {},
 };
 for (const arg of process.argv) {
     console.log(arg);
-    if (
-        arg.endsWith("node") ||
-        arg.endsWith("npm") ||
-        arg.endsWith("votes.js")
-    ) {
+    if (arg.endsWith("votes.js")) {
         // skip
     } else if (arg.startsWith("--repos=")) {
         config.options.repositories = arg.slice(8).split(",");
@@ -41,6 +38,13 @@ if (!config.jsonDir || !config.options.repositories) {
     process.exit(1);
 }
 
+if (!existsSync(config.jsonDir)) {
+    mkdirSync(config.jsonDir, { recursive: true });
+}
+if (!existsSync(config.markdownDir)) {
+    mkdirSync(config.markdownDir, { recursive: true });
+}
+
 const votes = queryVotes(config);
 console.log(
     "Found",