@officexapp/vidfarm-devcli 0.21.54 → 0.21.56

package/dist/src/devcli/skill-docs.js

@@ -117,7 +117,8 @@ export const PACK_TOPICS = [
         blurb: "The 5-stage ladder — what the viewer knows, what the video must do, and what it may ask for" },
     { topic: "problem-angles", aliases: ["angle", "lenses", "problem-angle"], doc: "references/content-ideas.md", heading: "The problem angles",
         blurb: "44 angles on the problem — hold the frame, change the angle when a topic is \"already covered\"" },
-    { topic: "meme-recaption", aliases: ["meme", "recaption", "meme-caption", "meme_recaption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
+    { topic: "meme-recaption", // `meme_recaption` needs no alias: resolvePackTopic folds `_` to `-` first.
+        aliases: ["meme", "recaption", "meme-caption"], doc: "references/editor-workflows.md", heading: "Writing a meme recaption",
         blurb: "Recaption a meme at a pain or a win the niche knows — the cold-viewer test. Building one from scratch? the full format is vidfarm.cc/experimental/meme-recaption.md" },
     { topic: "product-explainer", aliases: ["product-explainers"], doc: "harnesses/product-explainer.HARNESS.md",
         blurb: "The product-explainer harness — the bundled base for explaining what a product does" },

package/dist/src/devcli/update-check.js

@@ -0,0 +1,340 @@
+// `vidfarm update-check` — is this install current?
+//
+// Vidfarm ships as TWO moving parts that are versioned TOGETHER: the `vidfarm`
+// agent skill (the workflows on disk) and the `vidfarm-devcli` (the command).
+// Updating one but not the other is the most common cause of "this command
+// doesn't exist" and "the skill says to do X but it fails" — the skill documents
+// routes and flags the installed CLI may not have yet. So this checks both and
+// reports them as one answer.
+//
+// It is built to be run by an AI AGENT on a cadence, not by a human on a whim:
+//   - `--quiet` prints ONE line (or nothing at all when current), so it can sit
+//     at the top of a session without burning context.
+//   - `--if-stale` is a no-op unless the last check is older than the interval,
+//     so "check at least once every 24 hours" costs one cheap call a day rather
+//     than one per command.
+//   - `--skip` records the user's "not now" so the agent stops asking. A prompt
+//     that cannot be dismissed gets ignored, and then the real one is ignored too.
+//
+// BACKEND-FREE: Node built-ins plus one unauthenticated fetch of the public npm
+// registry and one of vidfarm.cc/skill.md. No key, no account, no wallet.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveDevcliHome } from "./auth-store.js";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+const PACKAGE_NAME = "@officexapp/vidfarm-devcli";
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const DEFAULT_HOST = "https://vidfarm.cc";
+/** "at least once every 24 hours" — the cadence SKILL.md asks agents to keep. */
+export const DEFAULT_STALE_HOURS = 24;
+/** Never let a version probe hold up the real work. */
+const FETCH_TIMEOUT_MS = 6000;
+// ── semver ───────────────────────────────────────────────────────────────────
+/**
+ * Compare two semvers numerically. A STRING compare is the trap here: "0.9.0"
+ * sorts above "0.21.55", which would report a current install as ahead of the
+ * registry and silently suppress every update prompt.
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => v.trim().replace(/^v/, "").split("-")[0].split(".").map((part) => {
+        const n = Number(part);
+        return Number.isFinite(n) ? n : 0;
+    });
+    const left = parse(a);
+    const right = parse(b);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const diff = (left[i] ?? 0) - (right[i] ?? 0);
+        if (diff !== 0)
+            return diff < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** Which part moved: a major bump is the one that can break a documented flow. */
+export function bumpKind(from, to) {
+    const parse = (v) => v.trim().replace(/^v/, "").split("-")[0].split(".").map((p) => Number(p) || 0);
+    const [aMajor = 0, aMinor = 0, aPatch = 0] = parse(from);
+    const [bMajor = 0, bMinor = 0, bPatch = 0] = parse(to);
+    if (bMajor !== aMajor)
+        return "major";
+    if (bMinor !== aMinor)
+        return "minor";
+    if (bPatch !== aPatch)
+        return "patch";
+    return "none";
+}
+// ── what is installed ────────────────────────────────────────────────────────
+/** Walk up from this module to the package root and read its version. */
+export function installedDevcliVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i += 1) {
+        const candidate = path.join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.version && (pkg.name === PACKAGE_NAME || pkg.name === "vidfarm-devcli" || i > 0)) {
+                    return String(pkg.version);
+                }
+            }
+            catch {
+                // keep walking — a malformed package.json higher up is not fatal
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * `version:` out of a SKILL.md front-matter block. Deliberately tiny — the same
+ * stance as the harness front-matter reader: a pack that needs a YAML parser to
+ * state its own version has stopped being legible to the human maintaining it.
+ */
+export function readSkillVersion(markdown) {
+    const front = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    const body = front ? front[1] : markdown.slice(0, 2000);
+    const found = body.match(/^\s*(?:skill_version|version)\s*:\s*["']?v?([0-9]+(?:\.[0-9]+)*)["']?\s*$/m);
+    return found ? found[1] : null;
+}
+/** The vidfarm skill pack installed on this machine, if there is one. */
+export function installedSkillPath() {
+    const roots = [process.cwd(), path.dirname(fileURLToPath(import.meta.url))];
+    for (const root of roots) {
+        let dir = root;
+        for (let i = 0; i < 6; i += 1) {
+            for (const rel of [
+                path.join(".agents", "skills", "vidfarm", "SKILL.md"),
+                path.join(".claude", "skills", "vidfarm", "SKILL.md")
+            ]) {
+                const candidate = path.join(dir, rel);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+// ── what is published ────────────────────────────────────────────────────────
+async function fetchText(url, headers = {}) {
+    try {
+        const response = await fetch(url, {
+            headers: { accept: "*/*", ...headers },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+        });
+        if (!response.ok)
+            return null;
+        return await response.text();
+    }
+    catch {
+        // Offline is a normal state for this CLI — the whole local half works with
+        // no network. A failed probe must never look like "you are out of date".
+        return null;
+    }
+}
+async function latestDevcliVersion() {
+    const text = await fetchText(REGISTRY_URL, { accept: "application/json" });
+    if (!text)
+        return null;
+    try {
+        const body = JSON.parse(text);
+        return body.version ? String(body.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function latestSkillVersion(host) {
+    const text = await fetchText(`${host.replace(/\/+$/, "")}/SKILL.md`);
+    return text ? readSkillVersion(text) : null;
+}
+function statePath(home) {
+    return path.join(resolveDevcliHome(home), "update-check.json");
+}
+export function readUpdateState(home) {
+    try {
+        return JSON.parse(readFileSync(statePath(home), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeUpdateState(next, home) {
+    const file = statePath(home);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(next, null, 2), "utf8");
+}
+/** Hours since the last check, or null if it has never run. */
+export function hoursSinceLastCheck(state, now = Date.now()) {
+    if (!state.lastCheckedAt)
+        return null;
+    const then = Date.parse(state.lastCheckedAt);
+    if (!Number.isFinite(then))
+        return null;
+    return (now - then) / 3_600_000;
+}
+export async function runUpdateCheck(options = {}) {
+    const host = options.host || process.env.VIDFARM_HOST || DEFAULT_HOST;
+    const now = options.now ?? Date.now();
+    const state = readUpdateState(options.home);
+    const devcliInstalled = installedDevcliVersion();
+    const skillPath = installedSkillPath();
+    const skillInstalled = skillPath ? readSkillVersion(readFileSync(skillPath, "utf8")) : null;
+    const [devcliLatest, skillLatest] = await Promise.all([latestDevcliVersion(), latestSkillVersion(host)]);
+    const offline = devcliLatest === null && skillLatest === null;
+    const devcliBehind = Boolean(devcliInstalled && devcliLatest && compareSemver(devcliInstalled, devcliLatest) < 0);
+    const skillBehind = Boolean(skillInstalled && skillLatest && compareSemver(skillInstalled, skillLatest) < 0);
+    // The version the user would be moving TO — a skip is recorded against it, so
+    // a NEWER release always asks again rather than staying silent forever.
+    const target = devcliLatest && skillLatest
+        ? (compareSemver(devcliLatest, skillLatest) >= 0 ? devcliLatest : skillLatest)
+        : (devcliLatest ?? skillLatest ?? "");
+    const skipped = Boolean(state.skippedVersion && target && compareSemver(target, state.skippedVersion) <= 0);
+    const report = {
+        devcli: {
+            installed: devcliInstalled,
+            latest: devcliLatest,
+            behind: devcliBehind,
+            bump: devcliInstalled && devcliLatest ? bumpKind(devcliInstalled, devcliLatest) : "none"
+        },
+        skill: { installed: skillInstalled, latest: skillLatest, behind: skillBehind, path: skillPath },
+        update_available: (devcliBehind || skillBehind) && !skipped,
+        suppressed: (devcliBehind || skillBehind) && skipped,
+        skipped,
+        checked_at: new Date(now).toISOString(),
+        hours_since_last_check: hoursSinceLastCheck(state, now),
+        offline
+    };
+    // Only a check that actually reached the network resets the clock. Stamping it
+    // while offline would suppress the next 24 hours of checks on no information.
+    if (!offline)
+        writeUpdateState({ ...state, lastCheckedAt: report.checked_at }, options.home);
+    return report;
+}
+// ── the command ──────────────────────────────────────────────────────────────
+export const UPDATE_CHECK_HELP = `vidfarm update-check — is this install current?
+
+  update-check                 Check both halves (skill + devcli) and print the verdict
+    --if-stale [--hours 24]    No-op unless the last check is older than N hours.
+                               THIS is the one to put in an agent's session opener.
+    --quiet                    One line, and NOTHING at all when already current
+    --json                     Structured: {devcli, skill, update_available, ...}
+    --skip                     Record "not now" for the current latest version.
+                               A NEWER release asks again; this one stays quiet.
+    --unskip                   Clear that, and ask again from now on
+    --host <url>               Where to read the published SKILL.md (default vidfarm.cc)
+
+  The skill and the devcli are versioned TOGETHER. Updating one without the other
+  is the most common cause of "that command doesn't exist" and "the skill says to
+  do X but it fails". Update both: https://vidfarm.cc/update.md`;
+export async function runUpdateCheckCommand(argv) {
+    const { parseArgs } = await import("node:util");
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            json: { type: "boolean" },
+            quiet: { type: "boolean" },
+            "if-stale": { type: "boolean" },
+            hours: { type: "string" },
+            skip: { type: "boolean" },
+            unskip: { type: "boolean" },
+            host: { type: "string" },
+            help: { type: "boolean" }
+        }
+    });
+    const values = parsed.values;
+    if (values.help) {
+        console.log(UPDATE_CHECK_HELP);
+        return;
+    }
+    if (values.unskip) {
+        const state = readUpdateState();
+        delete state.skippedVersion;
+        delete state.skippedAt;
+        writeUpdateState(state);
+        console.log(`${GREEN}✓${RESET} Update prompts re-enabled.`);
+        return;
+    }
+    // `--if-stale` is what makes a 24-hour cadence cheap: the agent can call this
+    // at the top of every session and it costs one network round-trip a day.
+    if (values["if-stale"]) {
+        const hours = Number(values.hours ?? DEFAULT_STALE_HOURS);
+        const since = hoursSinceLastCheck(readUpdateState());
+        if (since !== null && since < (Number.isFinite(hours) ? hours : DEFAULT_STALE_HOURS)) {
+            if (values.json)
+                console.log(JSON.stringify({ checked: false, hours_since_last_check: since }, null, 2));
+            else if (!values.quiet)
+                console.log(`${DIM}Checked ${since.toFixed(1)}h ago — skipping (next check after ${hours}h).${RESET}`);
+            return;
+        }
+    }
+    const report = await runUpdateCheck({ host: values.host });
+    if (values.skip) {
+        const target = report.devcli.latest ?? report.skill.latest;
+        if (target) {
+            writeUpdateState({ ...readUpdateState(), skippedVersion: target, skippedAt: new Date().toISOString() });
+            console.log(`${GREEN}✓${RESET} Skipped ${BOLD}${target}${RESET}. A newer release will ask again — ${DIM}vidfarm update-check --unskip${RESET} to undo.`);
+        }
+        else {
+            console.log(`${DIM}Nothing to skip — could not read the published versions.${RESET}`);
+        }
+        return;
+    }
+    if (values.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (report.offline) {
+        if (!values.quiet)
+            console.log(`${DIM}Could not reach the registry or ${values.host ?? DEFAULT_HOST} — skipping the version check. Everything local still works.${RESET}`);
+        return;
+    }
+    if (!report.update_available) {
+        if (values.quiet)
+            return; // silence is the point of --quiet when current
+        const parts = [
+            `devcli ${report.devcli.installed ?? "?"}`,
+            `skill ${report.skill.installed ?? "not installed"}`
+        ];
+        console.log(`${GREEN}✓${RESET} Vidfarm is current ${DIM}(${parts.join(" · ")})${RESET}`);
+        if (report.suppressed)
+            console.log(`  ${DIM}An update is available but you skipped it: vidfarm update-check --unskip${RESET}`);
+        return;
+    }
+    const lines = [];
+    if (report.devcli.behind)
+        lines.push(`  devcli  ${BOLD}${report.devcli.installed}${RESET} → ${BOLD}${GREEN}${report.devcli.latest}${RESET} ${DIM}(${report.devcli.bump})${RESET}`);
+    if (report.skill.behind)
+        lines.push(`  skill   ${BOLD}${report.skill.installed}${RESET} → ${BOLD}${GREEN}${report.skill.latest}${RESET}`);
+    if (report.skill.installed === null && report.skill.latest) {
+        lines.push(`  skill   ${DIM}not installed${RESET} → ${BOLD}${GREEN}${report.skill.latest}${RESET} ${DIM}(vidfarm skills add vidfarm)${RESET}`);
+    }
+    if (values.quiet) {
+        console.log(`${YELLOW}Vidfarm update available${RESET}${DIM} — ${report.devcli.behind ? `devcli ${report.devcli.installed}→${report.devcli.latest}` : ""}${report.devcli.behind && report.skill.behind ? ", " : ""}${report.skill.behind ? `skill ${report.skill.installed}→${report.skill.latest}` : ""} · vidfarm update-check for detail, --skip to dismiss${RESET}`);
+        return;
+    }
+    console.log(`${YELLOW}⟳ A Vidfarm update is available.${RESET}`);
+    for (const line of lines)
+        console.log(line);
+    console.log("");
+    if (report.devcli.bump === "major") {
+        console.log(`${YELLOW}This is a MAJOR bump${RESET}${DIM} — read the breaking-change notes before you assume an old workflow still applies.${RESET}`);
+    }
+    console.log(`${DIM}Update BOTH halves together — they are versioned together, and updating one alone is the${RESET}`);
+    console.log(`${DIM}usual cause of "that command doesn't exist". The runbook: ${RESET}https://vidfarm.cc/update.md`);
+    console.log("");
+    console.log(`  ${BOLD}npm i -g ${PACKAGE_NAME}@latest${RESET}  ${DIM}&&${RESET}  ${BOLD}vidfarm skills add vidfarm${RESET}`);
+    console.log("");
+    console.log(`${DIM}Not now? ${RESET}vidfarm update-check --skip${DIM} — this version stays quiet, a newer one asks again.${RESET}`);
+}
+//# sourceMappingURL=update-check.js.map