@dadado/agent-kit-cli 5.15.0 → 5.16.0

package/dist/update-Q4EBIRUB.js

@@ -0,0 +1,260 @@
+import {
+  NON_INTERACTIVE_ROOT_ARGS,
+  syncFromManifest
+} from "./chunk-5OXPNVCF.js";
+import {
+  formatSkippedSymlinks,
+  logApplyStats
+} from "./chunk-HS7LVVLO.js";
+import {
+  REGISTRY_CLI_ARGS,
+  resolveRegistryFromCli
+} from "./chunk-XWPO3VYQ.js";
+import {
+  CLAUDE_SETTINGS_REL,
+  formatClaudeSettingsDrift,
+  planClaudeSettingsDrift,
+  writeClaudeSessionStartHook
+} from "./chunk-CGTE7DHN.js";
+import "./chunk-MAPOQEA2.js";
+import {
+  withCliProgress
+} from "./chunk-QTON2GQX.js";
+import {
+  logger
+} from "./chunk-ZB43YMHW.js";
+import {
+  RootRefusedError,
+  confirmProjectRoot,
+  isNonInteractive,
+  syncPathCliToRuntime
+} from "./chunk-VGZBARQC.js";
+import "./chunk-4IWG5CVE.js";
+import {
+  checkForUpdates,
+  compareSemver,
+  normalizeSemver,
+  readLocalKitVersion
+} from "./chunk-XZZAVHH4.js";
+import "./chunk-NQ7IQ5XT.js";
+import "./chunk-YGBBHKBE.js";
+import "./chunk-6QV2BFGA.js";
+import {
+  buildManifest,
+  isProtectedPath,
+  loadAgentKitManifest,
+  resolveProtectedGlobs,
+  saveManifest,
+  seedManagedHashLedger
+} from "./chunk-VS2JD2XC.js";
+import "./chunk-5VCOWTTP.js";
+import {
+  KIT_PACKAGE_SPEC,
+  KIT_VERSION
+} from "./chunk-7HDQEK6T.js";
+import "./chunk-77V75A7O.js";
+
+// src/commands/update.ts
+import { defineCommand } from "citty";
+var updateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: "Re-apply L0/packs/skills from the registry (never overwrites L3). --check = notify-only."
+  },
+  args: {
+    cwd: {
+      type: "string",
+      default: process.cwd()
+    },
+    check: {
+      type: "boolean",
+      description: "Check-only: compare installed version to the resolved registry (public tags, or --registry local checkout); never apply L0 writes",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable JSON (with --check)",
+      default: false
+    },
+    "respect-prefs": {
+      type: "boolean",
+      description: "Honor updateCheck.enabled and intervalDays from .cursor/context/config.json (hooks)",
+      default: false
+    },
+    stamp: {
+      type: "boolean",
+      description: "Persist updateCheck.lastCheckedAt after a network check",
+      default: false
+    },
+    "seed-overlay": {
+      type: "boolean",
+      description: "Seed the managed-hash ledger from current local overlay files before applying (factory/dogfood only; consumers should not use this)",
+      default: false
+    },
+    "allow-stale-cli": {
+      type: "boolean",
+      description: "Apply even when this CLI is older than the registry it is syncing from; the manifest is then stamped with this CLI's version, not the registry's (factory/dev only)",
+      default: false
+    },
+    claude: {
+      type: "boolean",
+      description: "Also apply the ledger-aware Claude settings merge (.claude/settings.json + ledger) with install --claude authority; operator opt-in, never from hooks or plan-loop",
+      default: false
+    },
+    ...NON_INTERACTIVE_ROOT_ARGS,
+    ...REGISTRY_CLI_ARGS
+  },
+  async run({ args }) {
+    if (args.check) {
+      const result = await checkForUpdates(args.cwd, {
+        respectPrefs: Boolean(args["respect-prefs"]),
+        stamp: Boolean(args.stamp),
+        publicRegistryUrl: typeof args.url === "string" && args.url ? args.url : void 0,
+        registryPath: typeof args.registry === "string" && args.registry ? args.registry : void 0
+      });
+      if (args.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const line = `[${result.status}] ${result.message}`;
+        if (result.status === "error") logger.error(line);
+        else if (result.status === "update-available") logger.warn(line);
+        else if (result.status.startsWith("skipped-")) logger.warn(line);
+        else logger.info(line);
+      }
+      if (result.status === "error") process.exitCode = 2;
+      return;
+    }
+    const nonInteractive = args.yes || isNonInteractive();
+    let projectRoot;
+    try {
+      projectRoot = await confirmProjectRoot(args.cwd, {
+        nonInteractive,
+        command: "update",
+        forceRoot: args["force-root"]
+      });
+    } catch (err) {
+      if (err instanceof RootRefusedError) {
+        logger.error(err.message);
+        if (err.recovery) console.error(`
+${err.recovery}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      throw err;
+    }
+    const existing = await loadAgentKitManifest(projectRoot, { onWarning: logger.warn });
+    if (!existing) {
+      logger.warn("No .cursor/agent-kit.json \u2014 run agent-kit install first.");
+      return;
+    }
+    const registry = await resolveRegistryFromCli({
+      cwd: projectRoot,
+      registry: args.registry,
+      url: args.url,
+      ref: args.ref,
+      refresh: args.refresh,
+      manifest: existing
+    });
+    try {
+      logger.info(`Registry: ${registry.root} (${registry.source})`);
+      const registryVersionRaw = await readLocalKitVersion(registry.root);
+      const registryVersion = registryVersionRaw ? normalizeSemver(registryVersionRaw) : null;
+      const cliVersion = normalizeSemver(KIT_VERSION);
+      if (!registryVersion) {
+        logger.warn(
+          "Could not read a version from the registry checkout - skipping the CLI freshness check."
+        );
+      } else if (cliVersion && compareSemver(cliVersion, registryVersion) < 0 && !args["allow-stale-cli"]) {
+        logger.error(
+          `This CLI is v${cliVersion}, older than the registry it would apply (v${registryVersion}).`
+        );
+        console.error(
+          [
+            "",
+            "`agent-kit update` syncs registry content but stamps .cursor/agent-kit.json with the",
+            `version of the CLI running it, so applying now would write v${cliVersion} again, not v${registryVersion}.`,
+            "",
+            "Upgrade the binary first, then re-run:",
+            `  npm i -g ${KIT_PACKAGE_SPEC}@${registryVersion}`,
+            "  agent-kit update",
+            "",
+            `If npm has no ${registryVersion} yet, the release is still mid-publish`,
+            "(content sync and npm publish run in parallel) - retry shortly.",
+            "",
+            "Factory/dev checkouts that intend to apply newer content with an older",
+            "binary can pass --allow-stale-cli.",
+            ""
+          ].join("\n")
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const next = buildManifest({
+        version: KIT_VERSION,
+        profile: existing.profile,
+        packs: existing.packs,
+        skills: existing.skills,
+        protected: existing.protected,
+        // Restamp generatorVersion with the CLI that ran this apply so the two
+        // version fields in the manifest stop disagreeing after an update. The
+        // personalization result file itself is not regenerated here.
+        personalization: existing.personalization ? { ...existing.personalization, generatorVersion: KIT_VERSION } : void 0,
+        registryUrl: registry.url ?? existing.registry?.url,
+        registryRef: registry.ref ?? existing.registry?.ref
+      });
+      if (existing.overrides?.length) next.overrides = existing.overrides;
+      if (existing.unknownFields) next.unknownFields = existing.unknownFields;
+      if (next.version === existing.version && existing.installedAt) {
+        next.installedAt = existing.installedAt;
+      }
+      if (args["seed-overlay"]) {
+        await seedManagedHashLedger(projectRoot);
+        logger.info("Seeded managed-hash ledger from current local overlay files.");
+      }
+      const stats = await withCliProgress(
+        "update",
+        () => syncFromManifest(registry.root, projectRoot, next)
+      );
+      if (stats.skippedSymlink.length > 0) {
+        logApplyStats(stats);
+        logger.error(formatSkippedSymlinks(stats.skippedSymlink));
+        process.exitCode = 1;
+        return;
+      }
+      if (args.claude) {
+        const claude = await writeClaudeSessionStartHook(projectRoot, { authorized: true });
+        if (claude.status === "skipped-symlink") {
+          logApplyStats(stats);
+          logger.error(
+            `Claude settings not written: ${CLAUDE_SETTINGS_REL}, .claude/ or the ledger resolves outside the project (symlink). Nothing was changed there.`
+          );
+          process.exitCode = 1;
+          return;
+        }
+        if (claude.status === "unavailable") {
+          logger.warn(claude.instructions ?? `${CLAUDE_SETTINGS_REL} could not be merged.`);
+        } else {
+          console.log(`Claude settings ${claude.status}: ${claude.relativePath}`);
+        }
+      } else {
+        const drift = await planClaudeSettingsDrift(projectRoot);
+        if (drift) {
+          const protectedPath = isProtectedPath(CLAUDE_SETTINGS_REL, resolveProtectedGlobs(next));
+          for (const line of formatClaudeSettingsDrift(drift, { protectedPath })) console.log(line);
+        }
+      }
+      await saveManifest(projectRoot, next);
+      logApplyStats(stats);
+      const transition = next.version === existing.version ? `unchanged at v${next.version}` : `v${existing.version} \u2192 v${next.version}`;
+      logger.success(`Update complete: ${transition} (L3 protected paths left untouched).`);
+      const sync = await syncPathCliToRuntime({ runtimeVersion: KIT_VERSION });
+      for (const line of sync.lines) console.log(line);
+    } finally {
+      await registry.unlock?.();
+    }
+  }
+});
+export {
+  updateCommand
+};

package/dist/validate-V2CW7J4B.js

@@ -0,0 +1,201 @@
+import {
+  validateHandoffText
+} from "./chunk-2YU2H7I6.js";
+import {
+  readStdinJson
+} from "./chunk-DE3LQFSJ.js";
+import {
+  checkHandoffGrowth
+} from "./chunk-IHROBTNM.js";
+
+// src/commands/validate.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import { defineCommand } from "citty";
+
+// src/invariants/plan-schema.ts
+var CITE = "agent-kit validate plan (.cursor/context/templates/plan.md)";
+function validatePlanFrontmatterText(text) {
+  const warnings = [];
+  const match = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!match?.[1]) {
+    warnings.push({
+      code: "missing-frontmatter",
+      message: "Plan file has no YAML frontmatter block.",
+      cite: CITE
+    });
+    return warnings;
+  }
+  const block = match[1];
+  if (!/^todos:\s*$/m.test(block) && !/^todos:\s*\[/m.test(block)) {
+    if (!/^todos:/m.test(block)) {
+      warnings.push({
+        code: "missing-todos",
+        message: "Plan frontmatter has no `todos:` key.",
+        cite: CITE
+      });
+    }
+  }
+  if (!/^name:\s*\S+/m.test(block)) {
+    warnings.push({
+      code: "missing-name",
+      message: "Plan frontmatter has no `name:` key.",
+      cite: CITE
+    });
+  }
+  const hasTodoItem = /^\s*- id:\s*\S+/m.test(block);
+  if (/^todos:/m.test(block) && !hasTodoItem && !/^todos:\s*\[\s*\]/m.test(block)) {
+    warnings.push({
+      code: "empty-todos",
+      message: "Plan frontmatter `todos:` has no `- id:` items.",
+      cite: CITE
+    });
+  }
+  return warnings;
+}
+
+// src/commands/validate.ts
+async function resolveEditedPath(cwd, explicit) {
+  if (explicit) {
+    const filePath2 = path.resolve(cwd, explicit);
+    try {
+      return { filePath: filePath2, content: await readFile(filePath2, "utf8") };
+    } catch {
+      return null;
+    }
+  }
+  const payload = await readStdinJson();
+  const rel = typeof payload.file_path === "string" && payload.file_path || typeof payload.path === "string" && payload.path || typeof payload.file === "string" && payload.file || "";
+  if (!rel) return null;
+  const filePath = path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+  try {
+    return { filePath, content: await readFile(filePath, "utf8") };
+  } catch {
+    return null;
+  }
+}
+function isHandoffPath(filePath) {
+  return filePath.replace(/\\/g, "/").endsWith(".cursor/HANDOFF.md");
+}
+function isPlanPath(filePath) {
+  const norm = filePath.replace(/\\/g, "/");
+  return norm.includes("/.cursor/plans/") && norm.endsWith(".plan.md");
+}
+var validateCommand = defineCommand({
+  meta: {
+    name: "validate",
+    description: "Advisory validators for HANDOFF / plan frontmatter (hook adapter)."
+  },
+  subCommands: {
+    handoff: defineCommand({
+      meta: { name: "handoff", description: "Validate HANDOFF machine fields" },
+      args: {
+        cwd: { type: "string", default: process.cwd() },
+        file: { type: "string", description: "Path to HANDOFF.md" },
+        json: { type: "boolean", default: true }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const fileArg = typeof args.file === "string" ? args.file : void 0;
+        const filePath = fileArg ? path.resolve(cwd, fileArg) : path.join(path.resolve(cwd), ".cursor", "HANDOFF.md");
+        let content = "";
+        try {
+          content = await readFile(filePath, "utf8");
+        } catch {
+          console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
+          return;
+        }
+        const warnings = [
+          ...validateHandoffText(content),
+          ...checkHandoffGrowth(content).map((w) => ({
+            ...w,
+            cite: "agent-kit handoff --prune (see .cursor/context/templates/handoff.md)"
+          }))
+        ];
+        console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
+      }
+    }),
+    plan: defineCommand({
+      meta: { name: "plan", description: "Validate plan frontmatter" },
+      args: {
+        cwd: { type: "string", default: process.cwd() },
+        file: { type: "string", description: "Path to *.plan.md" },
+        json: { type: "boolean", default: true }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const fileArg = typeof args.file === "string" ? args.file : void 0;
+        if (!fileArg) {
+          console.log(JSON.stringify({ ok: false, warnings: [{ message: "file required" }] }));
+          process.exitCode = 2;
+          return;
+        }
+        const filePath = path.resolve(cwd, fileArg);
+        let content = "";
+        try {
+          content = await readFile(filePath, "utf8");
+        } catch {
+          console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
+          return;
+        }
+        const warnings = validatePlanFrontmatterText(content);
+        console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
+      }
+    }),
+    "after-edit": defineCommand({
+      meta: {
+        name: "after-edit",
+        description: "Advisory afterFileEdit: annotate HANDOFF/plan issues (never block)"
+      },
+      args: {
+        cwd: { type: "string", default: process.cwd() }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const resolved = await resolveEditedPath(path.resolve(cwd));
+        if (!resolved) {
+          console.log(JSON.stringify({}));
+          return;
+        }
+        const { filePath, content } = resolved;
+        if (isHandoffPath(filePath)) {
+          const warnings = [
+            ...validateHandoffText(content).map((w) => w.message),
+            ...checkHandoffGrowth(content).map((w) => w.message)
+          ];
+          if (!warnings.length) {
+            console.log(JSON.stringify({}));
+            return;
+          }
+          const msg = warnings.join(" ");
+          console.log(
+            JSON.stringify({
+              user_message: msg,
+              agent_message: `${msg} Cite: agent-kit validate handoff.`
+            })
+          );
+          return;
+        }
+        if (isPlanPath(filePath)) {
+          const warnings = validatePlanFrontmatterText(content);
+          if (!warnings.length) {
+            console.log(JSON.stringify({}));
+            return;
+          }
+          const msg = warnings.map((w) => w.message).join(" ");
+          console.log(
+            JSON.stringify({
+              user_message: msg,
+              agent_message: `${msg} Cite: agent-kit validate plan.`
+            })
+          );
+          return;
+        }
+        console.log(JSON.stringify({}));
+      }
+    })
+  }
+});
+export {
+  validateCommand
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dadado/agent-kit-cli",
-  "version": "5.15.0",
+  "version": "5.16.0",
   "description": "Agent Kit CLI: HITL framework install and tooling for AI-assisted IDEs (rules, skills, plan/handoff, context).",
   "license": "PolyForm-Noncommercial-1.0.0",
   "type": "module",