@milehimikey/em 1.6.1 → 1.7.1

package/dist/cli/skillCheck.d.ts

@@ -0,0 +1,18 @@
+export type SkillCheckFindingCode = "skill-check-not-installed" | "skill-check-stamp-missing" | "skill-check-stamp-mismatch" | "skill-check-content-drift";
+export interface SkillCheckFinding {
+    code: SkillCheckFindingCode;
+    message: string;
+    vendoredStamp?: string | null;
+    installedVersion?: string;
+    driftedFiles?: string[];
+}
+export interface SkillCheckResult {
+    findings: SkillCheckFinding[];
+    ok: boolean;
+}
+/**
+ * Pure: compares vendoredDir against packagedDir (content) and installedVersion (em --version
+ * — injected, never re-derived; see src/cli.ts's PKG_VERSION) against the vendored SKILL.md's
+ * em-version: stamp. No process.exit, no console.
+ */
+export declare function checkSkillSync(packagedDir: string, vendoredDir: string, installedVersion: string): SkillCheckResult;

package/dist/cli/skillCheck.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// `em skill check` (MIL-93): checks a consuming repo's vendored skill copy for drift against
+// the em package actually installed — the downstream half of the skill-drift problem (the
+// in-repo half is MIL-92's skillVersionCheck.ts, which checks *this* repo's own package.json
+// against *its own* bundled skill across two git revisions). This check has no git revisions
+// at all: both sides are directories on disk right now, so unlike ledgerCheck.ts/
+// skillVersionCheck.ts there's no GitRunner to inject.
+//
+// Two independent signals, both reported (never short-circuited on the first):
+//  - the vendored SKILL.md's em-version: stamp vs. the installed em's own version
+//  - a full content diff against the packaged skill (reusing planSkillSync's hash-walk), which
+//    catches a hand-edited vendored file even when its stamp still happens to match — the
+//    ticket's explicit "stamp says current, content isn't" case.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractEmVersionStamp } from "./skillVersionCheck.js";
+import { planSkillSync } from "./skillSync.js";
+/**
+ * Pure: compares vendoredDir against packagedDir (content) and installedVersion (em --version
+ * — injected, never re-derived; see src/cli.ts's PKG_VERSION) against the vendored SKILL.md's
+ * em-version: stamp. No process.exit, no console.
+ */
+export function checkSkillSync(packagedDir, vendoredDir, installedVersion) {
+    if (!existsSync(vendoredDir)) {
+        return {
+            ok: false,
+            findings: [
+                {
+                    code: "skill-check-not-installed",
+                    message: `no vendored skill found at ${vendoredDir} — run \`em skill sync\` first`,
+                },
+            ],
+        };
+    }
+    const findings = [];
+    const skillMdPath = join(vendoredDir, "SKILL.md");
+    const vendoredStamp = existsSync(skillMdPath) ? extractEmVersionStamp(readFileSync(skillMdPath, "utf8")) : null;
+    if (vendoredStamp === null) {
+        findings.push({
+            code: "skill-check-stamp-missing",
+            message: `${skillMdPath} has no em-version: stamp — vendored copy predates MIL-92 or was hand-edited`,
+        });
+    }
+    else if (vendoredStamp !== installedVersion) {
+        findings.push({
+            code: "skill-check-stamp-mismatch",
+            message: `vendored skill's em-version: stamp (${vendoredStamp}) doesn't match installed em (${installedVersion}) — run \`em skill sync\``,
+            vendoredStamp,
+            installedVersion,
+        });
+    }
+    const plan = planSkillSync(packagedDir, vendoredDir);
+    if (plan.changes.length > 0) {
+        const driftedFiles = plan.changes.map((c) => c.relPath).sort();
+        findings.push({
+            code: "skill-check-content-drift",
+            message: `vendored skill differs from the packaged skill in ${driftedFiles.length} file(s) — run \`em skill sync\``,
+            driftedFiles,
+        });
+    }
+    return { findings, ok: findings.length === 0 };
+}
+//# sourceMappingURL=skillCheck.js.map

package/dist/cli/skillCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillCheck.js","sourceRoot":"","sources":["../../src/cli/skillCheck.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,6FAA6F;AAC7F,0FAA0F;AAC1F,6FAA6F;AAC7F,6FAA6F;AAC7F,kFAAkF;AAClF,uDAAuD;AACvD,EAAE;AACF,+EAA+E;AAC/E,kFAAkF;AAClF,+FAA+F;AAC/F,0FAA0F;AAC1F,iEAAiE;AAEjE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAqB/C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,EAAE,WAAmB,EAAE,gBAAwB;IAC/F,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,2BAA2B;oBACjC,OAAO,EAAE,8BAA8B,WAAW,gCAAgC;iBACnF;aACF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAwB,EAAE,CAAC;IAEzC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;IAClD,MAAM,aAAa,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEhH,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,GAAG,WAAW,8EAA8E;SACtG,CAAC,CAAC;IACL,CAAC;SAAM,IAAI,aAAa,KAAK,gBAAgB,EAAE,CAAC;QAC9C,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,4BAA4B;YAClC,OAAO,EAAE,uCAAuC,aAAa,iCAAiC,gBAAgB,2BAA2B;YACzI,aAAa;YACb,gBAAgB;SACjB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/D,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,2BAA2B;YACjC,OAAO,EAAE,qDAAqD,YAAY,CAAC,MAAM,kCAAkC;YACnH,YAAY;SACb,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;AACjD,CAAC"}

package/dist/cli/skillSync.d.ts

@@ -0,0 +1,22 @@
+export type SkillSyncFileChangeKind = "added" | "modified" | "removed";
+export interface SkillSyncFileChange {
+    relPath: string;
+    kind: SkillSyncFileChangeKind;
+}
+export interface SkillSyncPlan {
+    /** Sorted by relPath. Empty means vendoredDir already matches packagedDir exactly. */
+    changes: SkillSyncFileChange[];
+    /** Files present, identical, in both dirs — not listed in `changes`. */
+    unchangedCount: number;
+}
+/**
+ * Pure: compares packagedDir (source of truth) against vendoredDir (which may not exist yet —
+ * that's the fresh-sync case, not an error) by per-file sha256. No fs writes.
+ */
+export declare function planSkillSync(packagedDir: string, vendoredDir: string): SkillSyncPlan;
+/**
+ * Shell: applies a plan produced by planSkillSync — copies added/modified files from
+ * packagedDir into vendoredDir, deletes removed files from vendoredDir. Idempotent; a plan
+ * with no changes is a no-op. Creates vendoredDir (and any needed subdirectories) as needed.
+ */
+export declare function applySkillSync(plan: SkillSyncPlan, packagedDir: string, vendoredDir: string): void;

package/dist/cli/skillSync.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+// `em skill sync` (MIL-93): materializes/updates a consuming repo's vendored copy of the
+// event-modeling skill from the em package actually installed. Unlike `em ledger`/
+// skillVersionCheck.ts (which diff two *git revisions* of the same repo), this diffs two
+// *directories on disk right now* — the packaged skill bundled with the running em, and a
+// vendored copy in some other repo — so there's no GitRunner here at all.
+//
+// Contract: the vendored copy is read-only from the consuming repo's point of view. Local
+// edits are never merged — sync always makes vendoredDir byte-identical to packagedDir, the
+// same "you don't own this copy" stance rlm-blueprint's hand-rolled sync guard already
+// enforced by hand. That's why, unlike `em skill install`, there's no --force/confirmation
+// gate: overwriting is the entire point.
+//
+// Split into a pure plan (walk + hash, no writes) and a thin apply (the actual fs mutation) so
+// `em skill check` (src/cli/skillCheck.ts) can reuse planSkillSync's diff for its own
+// content-drift detection without performing any writes.
+import { existsSync, mkdirSync, copyFileSync, readFileSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+import { walkDir } from "../util/walkDir.js";
+function sha256(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+/**
+ * Pure: compares packagedDir (source of truth) against vendoredDir (which may not exist yet —
+ * that's the fresh-sync case, not an error) by per-file sha256. No fs writes.
+ */
+export function planSkillSync(packagedDir, vendoredDir) {
+    const packagedFiles = new Set(walkDir(packagedDir));
+    const vendoredFiles = new Set(existsSync(vendoredDir) ? walkDir(vendoredDir) : []);
+    const allPaths = [...new Set([...packagedFiles, ...vendoredFiles])].sort();
+    const changes = [];
+    let unchangedCount = 0;
+    for (const relPath of allPaths) {
+        const inPackaged = packagedFiles.has(relPath);
+        const inVendored = vendoredFiles.has(relPath);
+        if (inPackaged && !inVendored) {
+            changes.push({ relPath, kind: "added" });
+        }
+        else if (!inPackaged && inVendored) {
+            changes.push({ relPath, kind: "removed" });
+        }
+        else if (sha256(join(packagedDir, relPath)) !== sha256(join(vendoredDir, relPath))) {
+            changes.push({ relPath, kind: "modified" });
+        }
+        else {
+            unchangedCount++;
+        }
+    }
+    return { changes, unchangedCount };
+}
+/**
+ * Shell: applies a plan produced by planSkillSync — copies added/modified files from
+ * packagedDir into vendoredDir, deletes removed files from vendoredDir. Idempotent; a plan
+ * with no changes is a no-op. Creates vendoredDir (and any needed subdirectories) as needed.
+ */
+export function applySkillSync(plan, packagedDir, vendoredDir) {
+    for (const change of plan.changes) {
+        const dest = join(vendoredDir, change.relPath);
+        if (change.kind === "removed") {
+            rmSync(dest);
+        }
+        else {
+            mkdirSync(dirname(dest), { recursive: true });
+            copyFileSync(join(packagedDir, change.relPath), dest);
+        }
+    }
+}
+//# sourceMappingURL=skillSync.js.map

package/dist/cli/skillSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillSync.js","sourceRoot":"","sources":["../../src/cli/skillSync.ts"],"names":[],"mappings":"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"}

package/dist/cli/skillVersionCheck.d.ts

@@ -0,0 +1,32 @@
+import { GitRunner } from "./diff-inputs.js";
+export type SkillVersionFindingCode = "skill-version-stamp-not-bumped" | "skill-version-stamp-stray-bump" | "skill-version-stamp-removed";
+export interface SkillVersionFinding {
+    code: SkillVersionFindingCode;
+    message: string;
+    oldPkgVersion: string;
+    newPkgVersion: string;
+    oldStamp: string | null;
+    newStamp: string | null;
+}
+/** Why no finding could be produced — a state the check can't prove anything from, not a
+ *  defect. `stamp-missing` covers the field not existing at EITHER revision (never adopted in
+ *  this span) — distinct from it existing at `from` and being deleted by `to`, which is a
+ *  `skill-version-stamp-removed` finding, not a skip. */
+export type SkillVersionSkipReason = "package-json-unreadable" | "skill-md-unreadable" | "stamp-missing";
+export interface SkillVersionCheckResult {
+    finding: SkillVersionFinding | null;
+    skipped: SkillVersionSkipReason | null;
+}
+/** Pull `em-version: X` out of a `---\n...\n---` frontmatter block. Minimal and single-purpose
+ *  — SKILL.md's frontmatter is two plain scalar keys plus a folded `description:` block, not
+ *  the richer schema src/catalog/sliceDoc.ts parses, so this doesn't reuse that parser.
+ *  Exported for reuse by src/cli/skillCheck.ts (MIL-93), which needs the same extraction to
+ *  compare a vendored copy's stamp against the installed em's own version — no reason to
+ *  duplicate the regex a second time. */
+export declare function extractEmVersionStamp(content: string): string | null;
+/**
+ * Compare `pkgJsonPath`'s version and `skillMdPath`'s `em-version:` stamp between revisions
+ * `from` and `to` (`to: null` = current working tree, matching `em diff`/`em ledger`). Pure
+ * aside from the injected `GitRunner` and fs reads — no process.exit, no console.
+ */
+export declare function checkSkillVersionStamp(pkgJsonPath: string, skillMdPath: string, from: string, to: string | null, runGit?: GitRunner): SkillVersionCheckResult;

package/dist/cli/skillVersionCheck.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+// MIL-92's version-stamp release gate: checks that package.json's `version` and SKILL.md's
+// `em-version:` frontmatter stamp move together across two revisions. Repo-internal — unlike
+// `em ledger` (MIL-89, src/cli/ledgerCheck.ts), which consumer repos run against their own
+// slice docs, this checks *this repo's own* package version against *this repo's own* bundled
+// skill, so it's never a shipped `em` subcommand — see scripts/check-skill-version-stamp.ts for
+// the thin CLI shim, and docs/ci.md's precedent framing for why a version/content-agreement
+// check needs two revisions rather than being folded into `em validate`.
+//
+// Both sides here are version strings compared for "did it move," not ledger's version-vs-
+// freeform-content comparison — the meaningful case is package.json's version changing without
+// the stamp following it (`skill-version-stamp-not-bumped`). Two more are flagged as cheap extra
+// coverage: a stray stamp edit with no matching package.json move (`-stray-bump`), and the
+// stamp being deleted outright (`-removed`, unconditional — regardless of whether package.json
+// also changed, since losing the mechanism entirely is a problem on its own; a code review on
+// this very PR caught an earlier version that silently skipped the pkgChanged+deleted-stamp
+// combination). The one case that stays clean rather than becoming a finding: the stamp's
+// first-ever introduction (no prior value to compare against) — the normal one-time bootstrap
+// of the field, not a stray edit (this check's own introducing PR, confirmed on CI, first).
+import { readFileSync } from "node:fs";
+import { realGit, resolveRevision } from "./diff-inputs.js";
+/** `to: null` reads the working tree directly (fs); a revision string resolves via git — same
+ *  `to: null` = working-tree convention `em diff`/`em ledger` use. */
+function readAt(path, rev, runGit) {
+    if (rev === null) {
+        try {
+            return { ok: true, content: readFileSync(path, "utf8") };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    const result = resolveRevision(path, rev, runGit);
+    return result.ok ? { ok: true, content: result.content } : { ok: false };
+}
+function extractPkgVersion(content) {
+    try {
+        const parsed = JSON.parse(content);
+        const version = parsed?.version;
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pull `em-version: X` out of a `---\n...\n---` frontmatter block. Minimal and single-purpose
+ *  — SKILL.md's frontmatter is two plain scalar keys plus a folded `description:` block, not
+ *  the richer schema src/catalog/sliceDoc.ts parses, so this doesn't reuse that parser.
+ *  Exported for reuse by src/cli/skillCheck.ts (MIL-93), which needs the same extraction to
+ *  compare a vendored copy's stamp against the installed em's own version — no reason to
+ *  duplicate the regex a second time. */
+export function extractEmVersionStamp(content) {
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatter)
+        return null;
+    const line = frontmatter[1].split("\n").find((l) => /^em-version:\s*/.test(l));
+    if (!line)
+        return null;
+    return line
+        .replace(/^em-version:\s*/, "")
+        .trim()
+        .replace(/^["']|["']$/g, "");
+}
+/**
+ * Compare `pkgJsonPath`'s version and `skillMdPath`'s `em-version:` stamp between revisions
+ * `from` and `to` (`to: null` = current working tree, matching `em diff`/`em ledger`). Pure
+ * aside from the injected `GitRunner` and fs reads — no process.exit, no console.
+ */
+export function checkSkillVersionStamp(pkgJsonPath, skillMdPath, from, to, runGit = realGit) {
+    const oldPkg = readAt(pkgJsonPath, from, runGit);
+    const newPkg = readAt(pkgJsonPath, to, runGit);
+    if (!oldPkg.ok || !newPkg.ok)
+        return { finding: null, skipped: "package-json-unreadable" };
+    const oldPkgVersion = extractPkgVersion(oldPkg.content);
+    const newPkgVersion = extractPkgVersion(newPkg.content);
+    if (oldPkgVersion === null || newPkgVersion === null)
+        return { finding: null, skipped: "package-json-unreadable" };
+    const oldSkill = readAt(skillMdPath, from, runGit);
+    const newSkill = readAt(skillMdPath, to, runGit);
+    if (!oldSkill.ok || !newSkill.ok)
+        return { finding: null, skipped: "skill-md-unreadable" };
+    const oldStamp = extractEmVersionStamp(oldSkill.content);
+    const newStamp = extractEmVersionStamp(newSkill.content);
+    // Never adopted anywhere in this revision span — nothing to compare. Distinct from the stamp
+    // being *removed* below: that's a regression, this is simply "the field doesn't exist yet."
+    if (oldStamp === null && newStamp === null)
+        return { finding: null, skipped: "stamp-missing" };
+    // The stamp's first-ever introduction (no em-version: key at `from`, one at `to`) has nothing
+    // to compare against either — not a stray edit, the normal one-time bootstrap of the field
+    // itself (e.g. this very check landing). Treat it as clean rather than a permanent
+    // false-positive on whichever PR happens to add the key.
+    if (oldStamp === null)
+        return { finding: null, skipped: null };
+    const pkgChanged = oldPkgVersion !== newPkgVersion;
+    // The stamp existed and is now gone entirely — a stronger signal than merely "left stale"
+    // (below), and one a naive "newStamp === null -> skip" early-out would otherwise swallow
+    // silently, including the worst case: package.json bumped in the very same change that
+    // deleted the stamp (caught in code review, MIL-92 PR #85 — no prior test combined
+    // pkgChanged: true with a deleted stamp). Always a finding, regardless of pkgChanged: removing
+    // the mechanism entirely is a problem on its own, not just when it coincides with a release.
+    if (newStamp === null) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-removed",
+                message: pkgChanged
+                    ? `SKILL.md's em-version: stamp (was ${oldStamp}) was removed entirely while package.json bumped ${oldPkgVersion} -> ${newPkgVersion}`
+                    : `SKILL.md's em-version: stamp (was ${oldStamp}) was removed entirely`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp: null,
+            },
+        };
+    }
+    const stampChanged = oldStamp !== newStamp;
+    if (pkgChanged && !stampChanged) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-not-bumped",
+                message: `package.json bumped ${oldPkgVersion} -> ${newPkgVersion} but SKILL.md's em-version: stamp stayed at ${newStamp}`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp,
+            },
+        };
+    }
+    if (!pkgChanged && stampChanged) {
+        return {
+            skipped: null,
+            finding: {
+                code: "skill-version-stamp-stray-bump",
+                message: `SKILL.md's em-version: stamp changed (${oldStamp ?? "(none)"} -> ${newStamp}) but package.json's version didn't move (still ${newPkgVersion})`,
+                oldPkgVersion,
+                newPkgVersion,
+                oldStamp,
+                newStamp,
+            },
+        };
+    }
+    return { finding: null, skipped: null };
+}
+//# sourceMappingURL=skillVersionCheck.js.map

package/dist/cli/skillVersionCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillVersionCheck.js","sourceRoot":"","sources":["../../src/cli/skillVersionCheck.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-export {};
+import { Command } from "commander";
+declare const program: Command;
+export { program };