@jskit-ai/jskit-cli 0.2.54 → 0.2.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.54",
+  "version": "0.2.56",
   "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.53",
-    "@jskit-ai/kernel": "0.1.45",
-    "@jskit-ai/shell-web": "0.1.44"
+    "@jskit-ai/jskit-catalog": "0.1.55",
+    "@jskit-ai/kernel": "0.1.47",
+    "@jskit-ai/shell-web": "0.1.46"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/appState.js

@@ -232,6 +232,7 @@ function removeEnvValue(content, key, expectedValue, previous) {
 }
 
 export {
+  directoryLooksLikeJskitAppRoot,
   resolveAppRootFromCwd,
   loadAppPackageJson,
   createDefaultLock,

package/src/server/commandHandlers/app.js

@@ -13,6 +13,7 @@ import { runAppLinkLocalPackagesCommand } from "./appCommands/linkLocalPackages.
 import { runAppReleaseCommand } from "./appCommands/release.js";
 import { runAppUpdatePackagesCommand } from "./appCommands/updatePackages.js";
 import { runAppVerifyCommand } from "./appCommands/verify.js";
+import { runAppVerifyUiCommand } from "./appCommands/verifyUi.js";
 
 function renderAppHelp(stream, definition = null) {
   const color = createColorFormatter(stream);
@@ -135,6 +136,9 @@ function createAppCommands(ctx = {}) {
     if (definition.name === "verify") {
       return runAppVerifyCommand(ctx, { appRoot, options, stdout, stderr });
     }
+    if (definition.name === "verify-ui") {
+      return runAppVerifyUiCommand(ctx, { appRoot, options, stdout, stderr });
+    }
     if (definition.name === "update-packages") {
       return runAppUpdatePackagesCommand(ctx, { appRoot, options, stdout, stderr });
     }

package/src/server/commandHandlers/appCommandCatalog.js

@@ -38,6 +38,30 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
       "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>",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--command <shell-command>",
+        description: "Targeted Playwright command to run, for example: npx playwright test tests/e2e/contacts.spec.ts -g filters."
+      }),
+      Object.freeze({
+        label: "--feature <label>",
+        description: "Short human label for the UI feature or flow that was verified."
+      }),
+      Object.freeze({
+        label: "--auth-mode <mode>",
+        description: "Auth path used by the Playwright flow: none | dev-auth-login-as | session-bootstrap | custom-local."
+      })
+    ]),
+    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."
+    ])
+  }),
   "update-packages": Object.freeze({
     name: "update-packages",
     summary: "Update installed @jskit-ai dependencies and refresh managed migrations.",
@@ -152,6 +176,11 @@ function buildAppCommandOptionMeta(subcommandName = "") {
   if (definition.name === "update-packages" || definition.name === "release") {
     optionMeta.registry = { inputType: "text" };
   }
+  if (definition.name === "verify-ui") {
+    optionMeta.command = { inputType: "text" };
+    optionMeta.feature = { inputType: "text" };
+    optionMeta["auth-mode"] = { inputType: "text" };
+  }
   if (definition.name === "link-local-packages") {
     optionMeta["repo-root"] = { inputType: "text" };
   }

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

@@ -80,6 +80,36 @@ function runExternalCommand(
   });
 }
 
+function runExternalShellCommand(
+  commandText,
+  {
+    cwd = "",
+    env = {},
+    stdout,
+    stderr,
+    quiet = false,
+    createCliError
+  } = {}
+) {
+  const result = spawnSync(String(commandText || ""), {
+    cwd: cwd || process.cwd(),
+    encoding: "utf8",
+    shell: true,
+    env: {
+      ...process.env,
+      ...env
+    }
+  });
+
+  return ensureCommandSucceeded(result, String(commandText || "").trim() || "shell command", {
+    createCliError,
+    cwd,
+    stdout,
+    stderr,
+    quiet
+  });
+}
+
 function formatUtcReleaseTimestamp(date = new Date()) {
   const year = date.getUTCFullYear();
   const month = String(date.getUTCMonth() + 1).padStart(2, "0");
@@ -265,6 +295,7 @@ export {
   normalizeText,
   isTruthyFlag,
   runExternalCommand,
+  runExternalShellCommand,
   formatUtcReleaseTimestamp,
   resolveLocalJskitBin,
   runLocalJskit,

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

@@ -0,0 +1,102 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runExternalShellCommand } from "./shared.js";
+import {
+  directoryLooksLikeJskitAppRoot
+} from "../../cliRuntime/appState.js";
+import {
+  UI_VERIFICATION_RECEIPT_RELATIVE_PATH,
+  UI_VERIFICATION_RECEIPT_VERSION,
+  UI_VERIFICATION_RUNNER,
+  isUiVerificationAuthMode,
+  resolveChangedUiFilesFromGit
+} from "../../shared/uiVerification.js";
+
+async function runAppVerifyUiCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
+  const { createCliError } = ctx;
+
+  if (options?.dryRun) {
+    throw createCliError("jskit app verify-ui does not support --dry-run.", { exitCode: 1 });
+  }
+
+  const inlineOptions =
+    options?.inlineOptions && typeof options.inlineOptions === "object" ? options.inlineOptions : {};
+  const command = String(inlineOptions.command || "").trim();
+  const feature = String(inlineOptions.feature || "").trim();
+  const authMode = String(inlineOptions["auth-mode"] || "").trim();
+
+  if (!command) {
+    throw createCliError("jskit app verify-ui requires --command <shell-command>.", {
+      exitCode: 1
+    });
+  }
+  if (!feature) {
+    throw createCliError("jskit app verify-ui requires --feature <label>.", {
+      exitCode: 1
+    });
+  }
+  if (!isUiVerificationAuthMode(authMode)) {
+    throw createCliError(
+      "jskit app verify-ui requires --auth-mode <none|dev-auth-login-as|session-bootstrap|custom-local>.",
+      {
+        exitCode: 1
+      }
+    );
+  }
+  if (!(await directoryLooksLikeJskitAppRoot(appRoot))) {
+    throw createCliError(
+      "jskit app verify-ui only works in a JSKIT app root (expected app.json or .jskit/lock.json).",
+      {
+        exitCode: 1
+      }
+    );
+  }
+
+  const changedUiState = resolveChangedUiFilesFromGit(appRoot);
+  if (!changedUiState.available) {
+    throw createCliError("jskit app verify-ui requires a git working tree so it can record changed UI files.", {
+      exitCode: 1
+    });
+  }
+  if (changedUiState.paths.length < 1) {
+    throw createCliError("jskit app verify-ui found no changed UI files in src/ or packages/.", {
+      exitCode: 1
+    });
+  }
+
+  runExternalShellCommand(command, {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+
+  const recordedAt = new Date().toISOString();
+  const receiptPath = path.join(appRoot, UI_VERIFICATION_RECEIPT_RELATIVE_PATH);
+  await mkdir(path.dirname(receiptPath), { recursive: true });
+  await writeFile(
+    receiptPath,
+    `${JSON.stringify(
+      {
+        version: UI_VERIFICATION_RECEIPT_VERSION,
+        runner: UI_VERIFICATION_RUNNER,
+        recordedAt,
+        feature,
+        command,
+        authMode,
+        changedUiFiles: changedUiState.paths
+      },
+      null,
+      2
+    )}\n`,
+    "utf8"
+  );
+
+  stdout.write(
+    `[verify-ui] wrote ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} for ${changedUiState.paths.length} changed UI file(s).\n`
+  );
+
+  return 0;
+}
+
+export { runAppVerifyUiCommand };

package/src/server/commandHandlers/health.js

@@ -7,9 +7,16 @@ import {
   ensureObject,
   sortStrings
 } from "../shared/collectionUtils.js";
+import {
+  UI_VERIFICATION_RECEIPT_RELATIVE_PATH,
+  isValidUiVerificationReceipt,
+  normalizeUiVerificationReceipt,
+  resolveChangedUiFilesFromGit
+} from "../shared/uiVerification.js";
 
 function createHealthCommands(ctx = {}) {
   const {
+    directoryLooksLikeJskitAppRoot,
     resolveAppRootFromCwd,
     loadLockFile,
     loadPackageRegistry,
@@ -621,6 +628,49 @@ function createHealthCommands(ctx = {}) {
     }
   }
 
+  async function collectUiVerificationDoctorIssues({ appRoot, issues }) {
+    if (!(await directoryLooksLikeJskitAppRoot(appRoot))) {
+      return;
+    }
+
+    const changedUiState = resolveChangedUiFilesFromGit(appRoot);
+    if (!changedUiState.available || changedUiState.paths.length < 1) {
+      return;
+    }
+
+    const receiptPath = path.join(appRoot, UI_VERIFICATION_RECEIPT_RELATIVE_PATH);
+    if (!(await fileExists(receiptPath))) {
+      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(", ")}`
+      );
+      return;
+    }
+
+    let parsedReceipt = null;
+    try {
+      parsedReceipt = JSON.parse(await readFile(receiptPath, "utf8"));
+    } catch (error) {
+      issues.push(
+        `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+      );
+      return;
+    }
+
+    const receipt = normalizeUiVerificationReceipt(parsedReceipt);
+    if (!isValidUiVerificationReceipt(receipt)) {
+      issues.push(
+        `[ui:verification] ${UI_VERIFICATION_RECEIPT_RELATIVE_PATH} is incomplete. It must include version, runner, recordedAt, feature, command, authMode, and changedUiFiles from jskit app verify-ui.`
+      );
+      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(", ")}`
+      );
+    }
+  }
+
   function collectDiLabelParityIssuesForPackage({ packageEntry, packageInsights }) {
     const packageId = String(packageEntry?.packageId || "").trim();
     const descriptor = ensureObject(packageEntry?.descriptor);
@@ -713,6 +763,10 @@ function createHealthCommands(ctx = {}) {
       appRoot,
       issues
     });
+    await collectUiVerificationDoctorIssues({
+      appRoot,
+      issues
+    });
 
     const payload = {
       appRoot,

package/src/server/core/buildCommandDeps.js

@@ -6,6 +6,7 @@ function createCommandHandlerDeps(deps = {}) {
     writeWrappedItems: deps.writeWrappedItems,
     normalizeRelativePath: deps.normalizeRelativePath,
     normalizeRelativePosixPath: deps.normalizeRelativePosixPath,
+    directoryLooksLikeJskitAppRoot: deps.directoryLooksLikeJskitAppRoot,
     resolveAppRootFromCwd: deps.resolveAppRootFromCwd,
     loadLockFile: deps.loadLockFile,
     loadPackageRegistry: deps.loadPackageRegistry,

package/src/server/core/createCliRunner.js

@@ -33,6 +33,7 @@ import {
   readFileBufferIfExists
 } from "../cliRuntime/ioAndMigrations.js";
 import {
+  directoryLooksLikeJskitAppRoot,
   resolveAppRootFromCwd,
   loadAppPackageJson,
   loadLockFile,
@@ -97,6 +98,7 @@ const commandHandlers = createCommandHandlers(
     writeWrappedItems,
     normalizeRelativePath,
     normalizeRelativePosixPath,
+    directoryLooksLikeJskitAppRoot,
     resolveAppRootFromCwd,
     loadLockFile,
     loadPackageRegistry,

package/src/server/shared/uiVerification.js

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const UI_VERIFICATION_RECEIPT_VERSION = 1;
+const UI_VERIFICATION_RECEIPT_RELATIVE_PATH = ".jskit/verification/ui.json";
+const UI_VERIFICATION_RUNNER = "playwright";
+const UI_VERIFICATION_AUTH_MODES = new Set([
+  "none",
+  "dev-auth-login-as",
+  "session-bootstrap",
+  "custom-local"
+]);
+
+const UI_EXTENSION_SET = new Set([
+  ".vue"
+]);
+
+const UI_SCRIPT_PATH_PATTERNS = Object.freeze([
+  /^src\/components\//u,
+  /^src\/composables\//u,
+  /^src\/layouts\//u,
+  /^src\/pages\//u,
+  /^src\/stores\//u,
+  /^src\/placement\.[A-Za-z0-9]+$/u,
+  /^packages\/[^/]+(?:-web)?\/src\/client\//u
+]);
+
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+function sortUniqueStrings(values = []) {
+  return [...new Set(values.map((value) => normalizeText(value)).filter(Boolean))].sort((left, right) =>
+    left.localeCompare(right)
+  );
+}
+
+function isUiVerificationAuthMode(value = "") {
+  return UI_VERIFICATION_AUTH_MODES.has(normalizeText(value));
+}
+
+function isUiVerificationPath(relativePath = "") {
+  const normalizedPath = normalizeText(relativePath).replace(/\\/g, "/");
+  if (!normalizedPath) {
+    return false;
+  }
+
+  if (UI_EXTENSION_SET.has(path.extname(normalizedPath).toLowerCase())) {
+    return normalizedPath.startsWith("src/") || normalizedPath.startsWith("packages/");
+  }
+
+  return UI_SCRIPT_PATH_PATTERNS.some((pattern) => pattern.test(normalizedPath));
+}
+
+function readGitPathList(appRoot = "", args = []) {
+  const result = spawnSync("git", Array.isArray(args) ? args : [], {
+    cwd: appRoot || process.cwd(),
+    encoding: "utf8"
+  });
+
+  if (result?.error || result?.status !== 0) {
+    return {
+      ok: false,
+      paths: []
+    };
+  }
+
+  return {
+    ok: true,
+    paths: sortUniqueStrings(String(result.stdout || "").split(/\r?\n/u))
+  };
+}
+
+function resolveChangedUiFilesFromGit(appRoot = "") {
+  const gitRepoCheck = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    cwd: appRoot || process.cwd(),
+    encoding: "utf8"
+  });
+
+  if (
+    gitRepoCheck?.error ||
+    gitRepoCheck?.status !== 0 ||
+    normalizeText(gitRepoCheck.stdout).toLowerCase() !== "true"
+  ) {
+    return {
+      available: false,
+      paths: []
+    };
+  }
+
+  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 changedPaths = sortUniqueStrings(
+    changedPathSets
+      .filter((entry) => entry.ok)
+      .flatMap((entry) => entry.paths)
+      .filter((relativePath) => isUiVerificationPath(relativePath))
+  );
+
+  return {
+    available: true,
+    paths: changedPaths
+  };
+}
+
+function normalizeUiVerificationReceipt(rawReceipt = {}) {
+  const receipt = rawReceipt && typeof rawReceipt === "object" && !Array.isArray(rawReceipt) ? rawReceipt : {};
+
+  return Object.freeze({
+    version: Number.isInteger(receipt.version) ? receipt.version : null,
+    runner: normalizeText(receipt.runner),
+    recordedAt: normalizeText(receipt.recordedAt),
+    feature: normalizeText(receipt.feature),
+    command: normalizeText(receipt.command),
+    authMode: normalizeText(receipt.authMode),
+    changedUiFiles: sortUniqueStrings(receipt.changedUiFiles)
+  });
+}
+
+function isValidUiVerificationReceipt(receipt) {
+  const normalizedReceipt = normalizeUiVerificationReceipt(receipt);
+
+  return (
+    normalizedReceipt.version === UI_VERIFICATION_RECEIPT_VERSION &&
+    normalizedReceipt.runner === UI_VERIFICATION_RUNNER &&
+    Boolean(normalizedReceipt.recordedAt) &&
+    Boolean(normalizedReceipt.feature) &&
+    Boolean(normalizedReceipt.command) &&
+    isUiVerificationAuthMode(normalizedReceipt.authMode)
+  );
+}
+
+export {
+  UI_VERIFICATION_AUTH_MODES,
+  UI_VERIFICATION_RECEIPT_RELATIVE_PATH,
+  UI_VERIFICATION_RECEIPT_VERSION,
+  UI_VERIFICATION_RUNNER,
+  isUiVerificationAuthMode,
+  isUiVerificationPath,
+  isValidUiVerificationReceipt,
+  normalizeUiVerificationReceipt,
+  resolveChangedUiFilesFromGit,
+  sortUniqueStrings
+};