Subchapter 9.11

Check

install/check.mjs

JavaScript87 lines5 KB

1// Is there a newer version? Read-only: compares this installed skill and its templates with the
2// repository they came from and prints one JSON. It changes nothing and runs no update; the
3// commands that would are in the output.
4//
5//   node <SKILL_ROOT>/install/check.mjs
6//
7// Two layers, two answers:
8//   skill      the installed skill folder (SKILL.md, guides/, install/) against the
9//              repository head: `current`, `behind` (with the files that differ), or `unknown`.
10//   templates  `templates/.source` commit against the head: `current` or `behind`, with the
11//              verticals touched and the commit messages in between.
12// Updating the skill changes how the agent works, not the project. Refreshing the templates changes
13// what future deploys copy and what the agent reads, not `src/`. Nothing here touches `src/`.

check.mjs on GitHub

import { mkdtempSync, readdirSync, rmSync } from "node:fs";

import { tmpdir } from "node:os";

import { basename, join, relative } from "node:path";

import { spawnSync } from "node:child_process";

import { SKILL_ROOT, TEMPLATES_PATH, installSource, templatesDir, templatesSource } from "./templates.mjs";

const git = (args, opts = {}) => spawnSync("git", args, { encoding: "utf8", timeout: 120_000, ...opts });

const skillName = basename(SKILL_ROOT);

const { repo } = installSource();

const out = { skill: {}, templates: {}, update: {} };

// ---- the repository: one clone of its history without file contents (small), read for both layers

const tmp = mkdtempSync(join(tmpdir(), "wix-headless-kit-check-"));

const clone = git(["clone", "--quiet", "--filter=blob:none", "--no-checkout", "--single-branch", repo, tmp]);

if (clone.status !== 0) {

rmSync(tmp, { recursive: true, force: true });

console.log(JSON.stringify({ error: `could not reach ${repo}: ${(clone.stderr || "").trim().slice(-200)}` }));

process.exit(1);

}

const head = git(["-C", tmp, "rev-parse", "HEAD"]).stdout.trim();

// ---- skill folder: every installed file's blob hash against the head's tree -------------------

{

const tree = git(["-C", tmp, "ls-tree", "-r", head, "--", `skills/${skillName}`]).stdout;

const remote = new Map(tree.split("\n").filter(Boolean).map((l) => { const [meta, path] = l.split("\t"); return [path.slice(`skills/${skillName}/`.length), meta.split(" ")[2]]; }));

const local = [];

const walk = (dir) => {

for (const e of readdirSync(dir, { withFileTypes: true })) {

const p = join(dir, e.name);

if (e.name === "templates" && dir === SKILL_ROOT) continue; // the templates are the other layer

if (e.isDirectory()) walk(p); else local.push(relative(SKILL_ROOT, p));

}

};

walk(SKILL_ROOT);

const differs = [], missingHere = [];

for (const f of local) if (remote.get(f) !== git(["hash-object", join(SKILL_ROOT, f)]).stdout.trim()) differs.push(f);

for (const f of remote.keys()) if (!local.includes(f)) missingHere.push(f);

out.skill = differs.length || missingHere.length

? { status: "behind", differs, ...(missingHere.length ? { missingHere } : {}), note: "a file that differs may also be one edited here; the update reinstalls the skill folder" }

: { status: "current" };

}

// ---- templates: the recorded commit against the head ------------------------------------------

let dir = null;

try { dir = templatesDir(); } catch (e) { out.templates = { status: "unknown", detail: e.message }; }

if (dir) {

const src = templatesSource(dir);

if (src.checkout) out.templates = { status: "checkout", dir };

else if (!src.commit) out.templates = { status: "unknown", detail: "no commit recorded in templates/.source" };

else if (src.commit === head) out.templates = { status: "current", commit: src.commit };

else {

out.templates = { status: "behind", commit: src.commit, head };

const files = git(["-C", tmp, "diff", "--name-only", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);

const log = git(["-C", tmp, "log", "--format=%s", `${src.commit}..${head}`, "--", TEMPLATES_PATH]).stdout.split("\n").filter(Boolean);

if (files.length || log.length) {

out.templates.commitsBehind = log.length;

out.templates.verticals = [...new Set(files.map((f) => f.split("/")[2]).filter((v) => v && !v.endsWith(".mjs") && !v.endsWith(".md")))].sort();

out.templates.commits = log.slice(0, 20);

} else {

out.templates.detail = git(["-C", tmp, "cat-file", "-e", src.commit]).status === 0 ? "no template changes between the two commits" : "the recorded commit is not in the repository's history (a branch that was deleted?)";

}

rmSync(tmp, { recursive: true, force: true });

// ---- what would act on each ------------------------------------------------------------------

const rel = relative(process.cwd(), SKILL_ROOT) || ".";

out.update = {

skill: `update ${skillName} the way it was installed (the plugin's update, or the skills CLI's)`,

templates: `node ${rel}/install/templates.mjs --refresh (then commit the changed files under ${rel}/templates)`,

note: "neither touches src/; a shipped fix reaches the project by comparing its copy with the template",

};

console.log(JSON.stringify(out, null, 2));