@justanarthur/just-github-actions-n-workflows-cli 0.0.0-beta.12 → 0.0.0-beta.15

package/dist/commands/init.js

@@ -3,6 +3,7 @@ import { checkbox, select } from "@inquirer/prompts";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { REPO, enrichWorkflows, fetchTags, fetchWorkflowContent, fetchWorkflowList, } from "../github.js";
+import { injectRefComment, mergeLockfile, readLockfile, writeLockfile, } from "../lockfile.js";
 export default class Init extends Command {
     static description = "Scaffold workflow files into .github/workflows/ of the current repo";
     static examples = [
@@ -74,7 +75,10 @@ export default class Init extends Command {
             return "main";
         const choices = [
             { name: `main ${ux.colorize("dim", "(latest)")}`, value: "main" },
-            ...tags.slice(0, 9).map((tag) => ({ name: tag, value: tag })),
+            ...tags.slice(0, 9).map((t) => ({
+                name: `${t.version} ${ux.colorize("dim", `(${t.tag})`)}`,
+                value: t.tag,
+            })),
         ];
         const ref = await select({
             message: "Pick a version",
@@ -128,6 +132,7 @@ export default class Init extends Command {
         this.log(ux.colorize("dim", `  fetching from ${REPO} @ ${ref}\n`));
         let created = 0;
         let skipped = 0;
+        const installed = [];
         for (const workflow of selected) {
             const targetPath = join(targetDir, workflow.file);
             if (!flags.force && existsSync(targetPath)) {
@@ -136,15 +141,24 @@ export default class Init extends Command {
                 continue;
             }
             try {
-                const content = await fetchWorkflowContent(workflow.file, ref);
+                let content = await fetchWorkflowContent(workflow.file, ref);
+                content = injectRefComment(content, ref);
                 writeFileSync(targetPath, content, "utf-8");
                 this.log(`  ${ux.colorize("green", "create")}  .github/workflows/${workflow.file}`);
+                installed.push({ name: workflow.name, file: workflow.file });
                 created++;
             }
             catch (error) {
                 this.log(`  ${ux.colorize("red", "error")}   ${workflow.file}: ${error.message}`);
             }
         }
+        // --- write lock file ---
+        if (installed.length > 0) {
+            const existing = readLockfile();
+            const lock = mergeLockfile(existing, ref, installed);
+            writeLockfile(lock);
+            this.log(ux.colorize("dim", `\n  lock file written → .github/workflows/.toolkit-lock.json`));
+        }
         return { created, skipped };
     }
     // ── step 4: secrets reminder ───────────────────────────

package/dist/commands/status.js

@@ -0,0 +1,53 @@
+// cli/src/commands/status.ts
+// ---
+// shows the current state of installed workflows:
+// version, install date, and whether each is outdated.
+// ---
+import { Command, Flags, ux } from "@oclif/core";
+import { fetchLatestTag } from "../github.js";
+import { readLockfile } from "../lockfile.js";
+export default class Status extends Command {
+    static description = "Show the status of installed workflows";
+    static examples = [
+        "<%= config.bin %> status",
+        "<%= config.bin %> status --ref v2.0.0",
+    ];
+    static flags = {
+        ref: Flags.string({
+            description: "Compare against this ref instead of the latest tag",
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Status);
+        const lock = readLockfile();
+        if (!lock || Object.keys(lock.workflows).length === 0) {
+            this.log(ux.colorize("yellow", "\n  no workflows installed — run `init` first.\n"));
+            return;
+        }
+        const targetRef = flags.ref ?? await fetchLatestTag();
+        const entries = Object.values(lock.workflows);
+        this.log();
+        this.log(ux.colorize("bold", "  installed workflows"));
+        this.log(ux.colorize("dim", `  latest: ${targetRef}\n`));
+        let outdatedCount = 0;
+        for (const entry of entries) {
+            const current = entry.ref === targetRef;
+            const icon = current ? ux.colorize("green", "✓") : ux.colorize("yellow", "⬆");
+            const refLabel = current
+                ? ux.colorize("green", entry.ref)
+                : `${ux.colorize("yellow", entry.ref)} → ${ux.colorize("green", targetRef)}`;
+            const date = ux.colorize("dim", new Date(entry.installedAt).toLocaleDateString());
+            this.log(`  ${icon} ${ux.colorize("cyan", entry.name.padEnd(28))} ${refLabel.padEnd(50)} ${date}`);
+            if (!current)
+                outdatedCount++;
+        }
+        this.log();
+        if (outdatedCount > 0) {
+            this.log(ux.colorize("yellow", `  ${outdatedCount} workflow(s) can be updated — run \`update\` to upgrade.\n`));
+        }
+        else {
+            this.log(ux.colorize("green", `  all ${entries.length} workflow(s) are up to date.\n`));
+        }
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/update.js

@@ -0,0 +1,108 @@
+// cli/src/commands/update.ts
+// ---
+// updates previously installed workflows to a newer version.
+// reads .toolkit-lock.json to find installed workflows, then
+// re-fetches them from the specified (or latest) git ref.
+// ---
+import { Command, Flags, ux } from "@oclif/core";
+import { confirm } from "@inquirer/prompts";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { REPO, fetchLatestTag, fetchWorkflowContent, } from "../github.js";
+import { injectRefComment, mergeLockfile, readLockfile, writeLockfile, } from "../lockfile.js";
+export default class Update extends Command {
+    static description = "Update installed workflows to a newer version";
+    static examples = [
+        "<%= config.bin %> update",
+        "<%= config.bin %> update --ref v2.0.0",
+        "<%= config.bin %> update --yes",
+    ];
+    static flags = {
+        ref: Flags.string({
+            description: "Target git ref to update to (branch, tag, or sha)",
+        }),
+        yes: Flags.boolean({
+            char: "y",
+            description: "Skip confirmation prompt",
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Update);
+        // --- read lock file ---
+        const lock = readLockfile();
+        if (!lock || Object.keys(lock.workflows).length === 0) {
+            this.error("No .toolkit-lock.json found. Run `init` first to install workflows.", { exit: 1 });
+        }
+        // --- resolve target ref ---
+        const targetRef = flags.ref ?? await fetchLatestTag();
+        const entries = Object.values(lock.workflows);
+        this.log();
+        this.log(ux.colorize("bold", "  workflow update check"));
+        this.log(ux.colorize("dim", `  target: ${targetRef}\n`));
+        // --- compare versions ---
+        const outdated = [];
+        const upToDate = [];
+        for (const entry of entries) {
+            if (entry.ref === targetRef) {
+                upToDate.push(entry);
+            }
+            else {
+                outdated.push(entry);
+            }
+        }
+        // --- print status table ---
+        for (const entry of entries) {
+            const current = entry.ref === targetRef;
+            const icon = current ? ux.colorize("green", "✓") : ux.colorize("yellow", "⬆");
+            const refLabel = current
+                ? ux.colorize("green", entry.ref)
+                : `${ux.colorize("yellow", entry.ref)} → ${ux.colorize("green", targetRef)}`;
+            this.log(`  ${icon} ${ux.colorize("cyan", entry.name.padEnd(28))} ${refLabel}`);
+        }
+        this.log();
+        if (outdated.length === 0) {
+            this.log(ux.colorize("green", `  all ${entries.length} workflow(s) are up to date at ${targetRef}\n`));
+            return;
+        }
+        // --- confirm ---
+        if (!flags.yes) {
+            const proceed = await confirm({
+                message: `Update ${outdated.length} workflow(s) to ${targetRef}?`,
+                default: true,
+            });
+            if (!proceed) {
+                this.log(ux.colorize("yellow", "\n  cancelled.\n"));
+                return;
+            }
+            this.log();
+        }
+        // --- update files ---
+        const targetDir = join(process.cwd(), ".github", "workflows");
+        let updated = 0;
+        let errors = 0;
+        const updatedEntries = [];
+        this.log(ux.colorize("dim", `  fetching from ${REPO} @ ${targetRef}\n`));
+        for (const entry of outdated) {
+            try {
+                let content = await fetchWorkflowContent(entry.file, targetRef);
+                content = injectRefComment(content, targetRef);
+                writeFileSync(join(targetDir, entry.file), content, "utf-8");
+                this.log(`  ${ux.colorize("green", "update")}  ${entry.file} ${ux.colorize("dim", `(${entry.ref} → ${targetRef})`)}`);
+                updatedEntries.push({ name: entry.name, file: entry.file });
+                updated++;
+            }
+            catch (error) {
+                this.log(`  ${ux.colorize("red", "error")}   ${entry.file}: ${error.message}`);
+                errors++;
+            }
+        }
+        // --- update lock file ---
+        if (updatedEntries.length > 0) {
+            const updatedLock = mergeLockfile(lock, targetRef, updatedEntries);
+            writeLockfile(updatedLock);
+        }
+        this.log(`\n  done — ${ux.colorize("green", `${updated} updated`)}, ${errors} errors, ${upToDate.length} already current\n`);
+    }
+}
+//# sourceMappingURL=update.js.map

package/dist/github.js

@@ -1,11 +1,16 @@
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
+const rootPkg = require("../../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}`;
+// --- root package tag prefix ---
+// tags for the root toolkit package follow `<root-name>@<version>`.
+// the CLI only shows these tags as version choices since workflows are part of the root package.
+const TAG_PREFIX = `${rootPkg.name}@`;
 export { REPO };
 // --- parse workflow header ---
 // extracts description and required secrets from the yaml header comment block.
@@ -40,14 +45,26 @@ export function parseWorkflowHeader(content) {
 }
 // --- api ---
 export async function fetchTags() {
-    const url = `${API_BASE}/tags?per_page=20`;
+    const url = `${API_BASE}/tags?per_page=100`;
     const res = await fetch(url, {
         headers: { Accept: "application/vnd.github.v3+json" }
     });
     if (!res.ok)
         return [];
     const tags = await res.json();
-    return tags.map((t) => t.name);
+    return tags
+        .map((t) => t.name)
+        .filter((name) => name.startsWith(TAG_PREFIX))
+        .map((name) => ({
+        tag: name,
+        version: name.slice(TAG_PREFIX.length)
+    }));
+}
+// --- fetchLatestTag ---
+// returns the most recent root toolkit tag, or "main" if none exist.
+export async function fetchLatestTag() {
+    const tags = await fetchTags();
+    return tags.length > 0 ? tags[0].tag : "main";
 }
 export async function fetchWorkflowList(gitRef) {
     const url = `${API_BASE}/contents/workflows?ref=${gitRef}`;

package/dist/lockfile.js

@@ -0,0 +1,72 @@
+// cli/src/lockfile.ts
+// ---
+// reads and writes .github/workflows/.toolkit-lock.json
+// tracks which version (git ref) each workflow was installed from.
+// ---
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+// --- constants ---
+const LOCKFILE_NAME = ".toolkit-lock.json";
+export function lockfilePath() {
+    return join(process.cwd(), ".github", "workflows", LOCKFILE_NAME);
+}
+// --- read ---
+export function readLockfile() {
+    const path = lockfilePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// --- write ---
+export function writeLockfile(lock) {
+    const path = lockfilePath();
+    writeFileSync(path, JSON.stringify(lock, null, 2) + "\n", "utf-8");
+}
+// --- merge ---
+// merges new entries into an existing lockfile (or creates a new one).
+export function mergeLockfile(existing, ref, entries) {
+    const now = new Date().toISOString();
+    const lock = existing ?? {
+        ref,
+        installedAt: now,
+        workflows: {},
+    };
+    lock.ref = ref;
+    lock.installedAt = now;
+    for (const entry of entries) {
+        lock.workflows[entry.file] = {
+            name: entry.name,
+            file: entry.file,
+            ref,
+            installedAt: now,
+        };
+    }
+    return lock;
+}
+// --- version comment ---
+// prepends a `# toolkit-ref: <ref>` comment to workflow content.
+export function injectRefComment(content, ref) {
+    const marker = "# toolkit-ref:";
+    const comment = `${marker} ${ref}`;
+    // replace existing marker if present
+    if (content.includes(marker)) {
+        return content.replace(/^# toolkit-ref:.*$/m, comment);
+    }
+    // prepend before first non-comment, non-empty line
+    const lines = content.split("\n");
+    const insertIdx = lines.findIndex((l) => l.trim() !== "" && !l.startsWith("#"));
+    if (insertIdx >= 0) {
+        lines.splice(insertIdx, 0, comment);
+    }
+    else {
+        lines.push(comment);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=lockfile.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justanarthur/just-github-actions-n-workflows-cli",
-  "version": "0.0.0-beta.12",
+  "version": "0.0.0-beta.15",
   "description": "Release automation toolkit — version bumping, npm publishing, docker publishing, VPS deployment via GitHub Actions composite actions",
   "type": "module",
   "bin": {