@jskit-ai/jskit-cli 0.2.68 → 0.2.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.68",
+  "version": "0.2.70",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.67",
-    "@jskit-ai/kernel": "0.1.59",
-    "@jskit-ai/shell-web": "0.1.58"
+    "@jskit-ai/jskit-catalog": "0.1.69",
+    "@jskit-ai/kernel": "0.1.61",
+    "@jskit-ai/shell-web": "0.1.60"
   },
   "engines": {
     "node": "20.x"

package/src/server/commandHandlers/appCommandCatalog.js

@@ -30,18 +30,24 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
   verify: Object.freeze({
     name: "verify",
     summary: "Run the JSKIT baseline app verification flow.",
-    usage: "jskit app verify",
-    options: Object.freeze([]),
+    usage: "jskit app verify [--against <base-ref>]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--against <base-ref>",
+        description: "Resolve changed-file checks against a branch, tag, or commit in addition to any local dirty UI files."
+      })
+    ]),
     defaults: Object.freeze([
       "Runs npm scripts lint, test, test:client, and build only when those scripts are present.",
       "Runs jskit doctor after the normal app checks.",
+      "Use --against <base-ref> in CI or PR validation so doctor evaluates changed-file checks against the branch delta too.",
       "The scaffolded npm run verify wrapper can append npm run --if-present verify:app afterwards."
     ])
   }),
   "verify-ui": Object.freeze({
     name: "verify-ui",
     summary: "Run a targeted Playwright command and write a UI verification receipt for jskit doctor.",
-    usage: "jskit app verify-ui --command <shell-command> --feature <label> --auth-mode <mode>",
+    usage: "jskit app verify-ui --command <shell-command> --feature <label> --auth-mode <mode> [--against <base-ref>]",
     options: Object.freeze([
       Object.freeze({
         label: "--command <shell-command>",
@@ -54,12 +60,16 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       Object.freeze({
         label: "--auth-mode <mode>",
         description: "Auth path used by the Playwright flow: none | dev-auth-login-as | session-bootstrap | custom-local."
+      }),
+      Object.freeze({
+        label: "--against <base-ref>",
+        description: "Record changed UI files against a branch, tag, or commit instead of only the current dirty worktree."
       })
     ]),
     defaults: Object.freeze([
       "Requires a git working tree so the receipt can record the currently changed UI files.",
       "Writes .jskit/verification/ui.json after the command succeeds.",
-      "Doctor expects the receipt to match the current dirty UI file set."
+      "Doctor expects the receipt to match the current dirty UI file set, or the same --against <base-ref> delta when used."
     ])
   }),
   "update-packages": Object.freeze({
@@ -176,6 +186,9 @@ function buildAppCommandOptionMeta(subcommandName = "") {
   if (definition.name === "update-packages" || definition.name === "release") {
     optionMeta.registry = { inputType: "text" };
   }
+  if (definition.name === "verify" || definition.name === "verify-ui") {
+    optionMeta.against = { inputType: "text" };
+  }
   if (definition.name === "verify-ui") {
     optionMeta.command = { inputType: "text" };
     optionMeta.feature = { inputType: "text" };

package/src/server/commandHandlers/appCommands/verify.js

@@ -9,6 +9,9 @@ const BASELINE_VERIFY_SCRIPTS = Object.freeze([
 
 async function runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
   const { createCliError } = ctx;
+  const inlineOptions =
+    options?.inlineOptions && typeof options.inlineOptions === "object" ? options.inlineOptions : {};
+  const against = String(inlineOptions.against || "").trim();
 
   if (options?.dryRun) {
     throw createCliError("jskit app verify does not support --dry-run.", { exitCode: 1 });
@@ -23,7 +26,12 @@ async function runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdou
     });
   }
 
-  await runLocalJskit(appRoot, ["doctor"], {
+  const doctorArgs = ["doctor"];
+  if (against) {
+    doctorArgs.push("--against", against);
+  }
+
+  await runLocalJskit(appRoot, doctorArgs, {
     stdout,
     stderr,
     createCliError

package/src/server/commandHandlers/appCommands/verifyUi.js

@@ -24,6 +24,7 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
   const command = String(inlineOptions.command || "").trim();
   const feature = String(inlineOptions.feature || "").trim();
   const authMode = String(inlineOptions["auth-mode"] || "").trim();
+  const against = String(inlineOptions.against || "").trim();
 
   if (!command) {
     throw createCliError("jskit app verify-ui requires --command <shell-command>.", {
@@ -52,16 +53,18 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
     );
   }
 
-  const changedUiState = resolveChangedUiFilesFromGit(appRoot);
+  const changedUiState = resolveChangedUiFilesFromGit(appRoot, { against });
   if (!changedUiState.available) {
-    throw createCliError("jskit app verify-ui requires a git working tree so it can record changed UI files.", {
-      exitCode: 1
-    });
+    const message = against
+      ? `jskit app verify-ui could not resolve changed UI files against ${JSON.stringify(against)}: ${changedUiState.error || "unknown git error"}.`
+      : "jskit app verify-ui requires a git working tree so it can record changed UI files.";
+    throw createCliError(message, { exitCode: 1 });
   }
   if (changedUiState.paths.length < 1) {
-    throw createCliError("jskit app verify-ui found no changed UI files in src/ or packages/.", {
-      exitCode: 1
-    });
+    const message = against
+      ? `jskit app verify-ui found no changed UI files in src/ or packages/ against ${JSON.stringify(against)}.`
+      : "jskit app verify-ui found no changed UI files in src/ or packages/.";
+    throw createCliError(message, { exitCode: 1 });
   }
 
   runExternalShellCommand(command, {
@@ -84,6 +87,7 @@ async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, std
         feature,
         command,
         authMode,
+        ...(against ? { against } : {}),
         changedUiFiles: changedUiState.paths
       },
       null,

package/src/server/commandHandlers/health.js

@@ -1154,20 +1154,32 @@ function createHealthCommands(ctx = {}) {
     }
   }
 
-  async function collectUiVerificationDoctorIssues({ appRoot, issues }) {
+  async function collectUiVerificationDoctorIssues({ appRoot, issues, against = "" }) {
     if (!(await directoryLooksLikeJskitAppRoot(appRoot))) {
       return;
     }
 
-    const changedUiState = resolveChangedUiFilesFromGit(appRoot);
-    if (!changedUiState.available || changedUiState.paths.length < 1) {
+    const normalizedAgainst = String(against || "").trim();
+    const changedUiState = resolveChangedUiFilesFromGit(appRoot, {
+      against: normalizedAgainst
+    });
+    if (!changedUiState.available) {
+      if (normalizedAgainst) {
+        issues.push(
+          `[ui:verification] could not resolve changed UI files against ${JSON.stringify(normalizedAgainst)}: ${changedUiState.error || "unknown git error"}`
+        );
+      }
+      return;
+    }
+    if (changedUiState.paths.length < 1) {
       return;
     }
 
     const receiptPath = path.join(appRoot, UI_VERIFICATION_RECEIPT_RELATIVE_PATH);
     if (!(await fileExists(receiptPath))) {
+      const againstSegment = normalizedAgainst ? ` --against ${JSON.stringify(normalizedAgainst)}` : "";
       issues.push(
-        `[ui:verification] changed UI files require a matching ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} receipt. Run jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>. Current files: ${changedUiState.paths.join(", ")}`
+        `[ui:verification] changed UI files require a matching ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} receipt. Run jskit app verify-ui${againstSegment} --command "<playwright command>" --feature "<label>" --auth-mode <mode>. Current files: ${changedUiState.paths.join(", ")}`
       );
       return;
     }
@@ -1190,6 +1202,13 @@ function createHealthCommands(ctx = {}) {
       return;
     }
 
+    if (normalizedAgainst && receipt.against !== normalizedAgainst) {
+      issues.push(
+        `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} was recorded against ${JSON.stringify(receipt.against || "<dirty-worktree>")} but doctor is checking against ${JSON.stringify(normalizedAgainst)}. Re-run jskit app verify-ui with the same --against value.`
+      );
+      return;
+    }
+
     if (JSON.stringify(receipt.changedUiFiles) !== JSON.stringify(changedUiState.paths)) {
       issues.push(
         `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} does not match the current changed UI file set. Re-run jskit app verify-ui after the latest UI edits. Current files: ${changedUiState.paths.join(", ")}`
@@ -1251,6 +1270,7 @@ function createHealthCommands(ctx = {}) {
 
   async function commandDoctor({ cwd, options, stdout }) {
     const appRoot = await resolveAppRootFromCwd(cwd);
+    const against = String(options?.inlineOptions?.against || "").trim();
     const { lock } = await loadLockFile(appRoot);
     const packageRegistry = await loadPackageRegistry();
     const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
@@ -1292,7 +1312,8 @@ function createHealthCommands(ctx = {}) {
     });
     await collectUiVerificationDoctorIssues({
       appRoot,
-      issues
+      issues,
+      against
     });
     await collectFeatureLaneDoctorIssues({
       appRoot,

package/src/server/core/commandCatalog.js

@@ -475,14 +475,15 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     defaults: Object.freeze([
       "Validates lock entries, managed files, and registry visibility.",
       "Reports issues as plain text by default.",
-      "Use --json for machine-readable diagnostics."
+      "Use --json for machine-readable diagnostics.",
+      "Use --against <base-ref> when changed-file checks should compare against a branch, tag, or commit."
     ]),
-    fullUse: "jskit doctor [--json]",
+    fullUse: "jskit doctor [--against <base-ref>] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandDoctor",
     allowedFlagKeys: Object.freeze(["json"]),
-    inlineOptionMode: "none",
-    allowedValueOptionNames: Object.freeze([])
+    inlineOptionMode: "enumerated",
+    allowedValueOptionNames: Object.freeze(["against"])
   }),
   "lint-descriptors": Object.freeze({
     command: "lint-descriptors",

package/src/server/shared/uiVerification.js

@@ -61,17 +61,26 @@ function readGitPathList(appRoot = "", args = []) {
   if (result?.error || result?.status !== 0) {
     return {
       ok: false,
-      paths: []
+      paths: [],
+      error: normalizeText(result?.stderr) || normalizeText(result?.error?.message)
     };
   }
 
   return {
     ok: true,
-    paths: sortUniqueStrings(String(result.stdout || "").split(/\r?\n/u))
+    paths: sortUniqueStrings(String(result.stdout || "").split(/\r?\n/u)),
+    error: ""
   };
 }
 
-function resolveChangedUiFilesFromGit(appRoot = "") {
+function resolveChangedPathsFromGit(
+  appRoot = "",
+  {
+    against = "",
+    pathspecs = ["src", "packages"]
+  } = {}
+) {
+  const normalizedAgainst = normalizeText(against);
   const gitRepoCheck = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
     cwd: appRoot || process.cwd(),
     encoding: "utf8"
@@ -84,26 +93,72 @@ function resolveChangedUiFilesFromGit(appRoot = "") {
   ) {
     return {
       available: false,
-      paths: []
+      paths: [],
+      against: normalizedAgainst,
+      mode: normalizedAgainst ? "against-base-ref" : "dirty-worktree",
+      error: "Current directory is not inside a git work tree."
     };
   }
 
-  const changedPathSets = [
-    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--cached", "--", "src", "packages"]),
-    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--", "src", "packages"]),
-    readGitPathList(appRoot, ["ls-files", "--others", "--exclude-standard", "--", "src", "packages"])
-  ];
+  const normalizedPathspecs = sortUniqueStrings(pathspecs);
+  const pathspecArgs = normalizedPathspecs.length > 0 ? ["--", ...normalizedPathspecs] : [];
+  const changedPathSets = [];
+
+  if (normalizedAgainst) {
+    const baseDiff = readGitPathList(appRoot, [
+      "diff",
+      "--name-only",
+      "--relative",
+      `${normalizedAgainst}...HEAD`,
+      ...pathspecArgs
+    ]);
+    if (!baseDiff.ok) {
+      return {
+        available: false,
+        paths: [],
+        against: normalizedAgainst,
+        mode: "against-base-ref",
+        error:
+          baseDiff.error ||
+          `Could not resolve git diff against ${JSON.stringify(normalizedAgainst)}.`
+      };
+    }
+    changedPathSets.push(baseDiff);
+  }
+
+  changedPathSets.push(
+    readGitPathList(appRoot, ["diff", "--name-only", "--relative", "--cached", ...pathspecArgs]),
+    readGitPathList(appRoot, ["diff", "--name-only", "--relative", ...pathspecArgs]),
+    readGitPathList(appRoot, ["ls-files", "--others", "--exclude-standard", ...pathspecArgs])
+  );
 
   const changedPaths = sortUniqueStrings(
     changedPathSets
       .filter((entry) => entry.ok)
       .flatMap((entry) => entry.paths)
-      .filter((relativePath) => isUiVerificationPath(relativePath))
   );
 
   return {
     available: true,
-    paths: changedPaths
+    paths: changedPaths,
+    against: normalizedAgainst,
+    mode: normalizedAgainst ? "against-base-ref" : "dirty-worktree",
+    error: ""
+  };
+}
+
+function resolveChangedUiFilesFromGit(appRoot = "", { against = "" } = {}) {
+  const changedPathState = resolveChangedPathsFromGit(appRoot, {
+    against,
+    pathspecs: ["src", "packages"]
+  });
+  if (!changedPathState.available) {
+    return changedPathState;
+  }
+
+  return {
+    ...changedPathState,
+    paths: changedPathState.paths.filter((relativePath) => isUiVerificationPath(relativePath))
   };
 }
 
@@ -117,6 +172,7 @@ function normalizeUiVerificationReceipt(rawReceipt = {}) {
     feature: normalizeText(receipt.feature),
     command: normalizeText(receipt.command),
     authMode: normalizeText(receipt.authMode),
+    against: normalizeText(receipt.against),
     changedUiFiles: sortUniqueStrings(receipt.changedUiFiles)
   });
 }
@@ -143,6 +199,7 @@ export {
   isUiVerificationPath,
   isValidUiVerificationReceipt,
   normalizeUiVerificationReceipt,
+  resolveChangedPathsFromGit,
   resolveChangedUiFilesFromGit,
   sortUniqueStrings
 };