@jskit-ai/jskit-cli 0.2.50 → 0.2.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.50",
+  "version": "0.2.51",
   "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.49",
-    "@jskit-ai/kernel": "0.1.41",
-    "@jskit-ai/shell-web": "0.1.40"
+    "@jskit-ai/jskit-catalog": "0.1.50",
+    "@jskit-ai/kernel": "0.1.42",
+    "@jskit-ai/shell-web": "0.1.41"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/appState.js

@@ -11,19 +11,41 @@ import {
 
 const LOCK_RELATIVE_PATH = ".jskit/lock.json";
 const LOCK_VERSION = 1;
+const APP_ROOT_MARKER_RELATIVE_PATHS = Object.freeze([
+  LOCK_RELATIVE_PATH,
+  "app.json"
+]);
+
+async function directoryLooksLikeJskitAppRoot(directoryPath) {
+  for (const relativePath of APP_ROOT_MARKER_RELATIVE_PATHS) {
+    if (await fileExists(path.join(directoryPath, relativePath))) {
+      return true;
+    }
+  }
+  return false;
+}
 
 async function resolveAppRootFromCwd(cwd) {
   const startDirectory = path.resolve(String(cwd || process.cwd()));
   let currentDirectory = startDirectory;
+  let fallbackPackageRoot = "";
 
   while (true) {
     const packageJsonPath = path.join(currentDirectory, "package.json");
     if (await fileExists(packageJsonPath)) {
-      return currentDirectory;
+      if (!fallbackPackageRoot) {
+        fallbackPackageRoot = currentDirectory;
+      }
+      if (await directoryLooksLikeJskitAppRoot(currentDirectory)) {
+        return currentDirectory;
+      }
     }
 
     const parentDirectory = path.dirname(currentDirectory);
     if (parentDirectory === currentDirectory) {
+      if (fallbackPackageRoot) {
+        return fallbackPackageRoot;
+      }
       throw createCliError(
         `Could not locate package.json starting from ${startDirectory}. Run jskit from an app directory (or a child directory of one).`
       );

package/src/server/cliRuntime/completion.js

@@ -1,6 +1,10 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { access, readdir, readFile } from "node:fs/promises";
+import {
+  buildAppCommandOptionMeta,
+  listAppCommandDefinitions
+} from "../commandHandlers/appCommandCatalog.js";
 import {
   COMMAND_IDS,
   isKnownCommandName,
@@ -1028,6 +1032,35 @@ async function completeCommand({ appRoot, words, cword, catalogModule }) {
   if (command === "generate") {
     return completeGenerateCommand({ appRoot, words, cword, catalogModule });
   }
+  if (command === "app") {
+    const appCommandNames = listAppCommandDefinitions().map((entry) => entry.name);
+    const currentTokenForApp = words[cword] ?? "";
+    const subcommandName = normalizeText(words[2]);
+    if (cword <= 2) {
+      return filterByPrefix(appCommandNames, currentTokenForApp);
+    }
+
+    if (!subcommandName || !appCommandNames.includes(subcommandName)) {
+      return filterByPrefix(appCommandNames, currentTokenForApp);
+    }
+
+    const previousTokenForApp = words[cword - 1] ?? "";
+    const optionMetaForApp = buildAppCommandOptionMeta(subcommandName);
+    return completeGenericContext({
+      appRoot,
+      currentToken: currentTokenForApp,
+      previousToken: previousTokenForApp,
+      optionMeta: optionMetaForApp,
+      tokensBeforeCurrent: words.slice(3, cword),
+      optionNames: uniqueSorted(Object.keys(optionMetaForApp)),
+      positionalCompleter: async ({ positionalIndex, currentToken: positionalCurrent }) => {
+        if (positionalIndex === 0) {
+          return filterByPrefix(["help"], positionalCurrent);
+        }
+        return [];
+      }
+    });
+  }
 
   const optionMeta = buildCommandOptionMeta(command, catalogModule);
   const optionNames = uniqueSorted(Object.keys(optionMeta));

package/src/server/commandHandlers/app.js

@@ -0,0 +1,161 @@
+import {
+  createColorFormatter,
+  writeWrappedLines
+} from "../shared/outputFormatting.js";
+import {
+  APP_SCRIPT_WRAPPERS,
+  buildAppCommandOptionMeta,
+  listAppCommandDefinitions,
+  resolveAppCommandDefinition
+} from "./appCommandCatalog.js";
+import { runAppAdoptManagedScriptsCommand } from "./appCommands/adoptManagedScripts.js";
+import { runAppLinkLocalPackagesCommand } from "./appCommands/linkLocalPackages.js";
+import { runAppReleaseCommand } from "./appCommands/release.js";
+import { runAppUpdatePackagesCommand } from "./appCommands/updatePackages.js";
+import { runAppVerifyCommand } from "./appCommands/verify.js";
+
+function renderAppHelp(stream, definition = null) {
+  const color = createColorFormatter(stream);
+  const lines = [];
+
+  if (!definition) {
+    lines.push(`Command: ${color.emphasis("app")}`);
+    lines.push("");
+    lines.push(color.heading("1) Minimal use"));
+    lines.push("   jskit app <subcommand>");
+    lines.push("");
+    lines.push(color.heading("2) Subcommands"));
+    for (const entry of listAppCommandDefinitions()) {
+      lines.push(`   - ${color.item(entry.name)}: ${entry.summary}`);
+    }
+    lines.push("");
+    lines.push(color.heading("3) Notes"));
+    lines.push("   - The scaffold keeps npm run shortcuts such as verify and jskit:update,");
+    lines.push("     but the maintained behavior lives here in jskit app.");
+    lines.push("   - Use jskit app <subcommand> help for subcommand-specific usage.");
+    lines.push("");
+    lines.push(color.heading("4) Scaffold wrappers"));
+    for (const [scriptName, scriptCommand] of Object.entries(APP_SCRIPT_WRAPPERS)) {
+      lines.push(`   - ${scriptName}: ${scriptCommand}`);
+    }
+    writeWrappedLines({
+      stdout: stream,
+      lines
+    });
+    return;
+  }
+
+  lines.push(`App subcommand: ${color.emphasis(definition.name)}`);
+  lines.push("");
+  lines.push(color.heading("1) Summary"));
+  lines.push(`   ${definition.summary}`);
+  lines.push("");
+  lines.push(color.heading("2) Use"));
+  lines.push(`   ${definition.usage}`);
+
+  if (definition.options.length > 0) {
+    lines.push("");
+    lines.push(color.heading("3) Options"));
+    for (const optionRow of definition.options) {
+      lines.push(`   - ${optionRow.label}: ${optionRow.description}`);
+    }
+  }
+
+  if (definition.defaults.length > 0) {
+    lines.push("");
+    lines.push(color.heading(definition.options.length > 0 ? "4) Defaults" : "3) Defaults"));
+    for (const defaultLine of definition.defaults) {
+      lines.push(`   - ${defaultLine}`);
+    }
+  }
+
+  writeWrappedLines({
+    stdout: stream,
+    lines
+  });
+}
+
+function createAppCommands(ctx = {}) {
+  const {
+    createCliError,
+    resolveAppRootFromCwd
+  } = ctx;
+
+  async function commandApp({ positional = [], options = {}, cwd = "", stdout, stderr }) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const firstToken = String(positional[0] || "").trim();
+    const secondToken = String(positional[1] || "").trim();
+
+    if (!firstToken) {
+      renderAppHelp(stdout);
+      return 0;
+    }
+
+    if (firstToken === "help") {
+      renderAppHelp(stdout, resolveAppCommandDefinition(secondToken));
+      return 0;
+    }
+
+    const definition = resolveAppCommandDefinition(firstToken);
+    if (!definition) {
+      throw createCliError(`Unknown app subcommand: ${firstToken}.`, {
+        renderUsage: () => renderAppHelp(stderr)
+      });
+    }
+
+    if (secondToken === "help") {
+      renderAppHelp(stdout, definition);
+      return 0;
+    }
+
+    const optionMeta = buildAppCommandOptionMeta(definition.name);
+    const supportedOptionNames = new Set(Object.keys(optionMeta));
+    const inlineOptionNames = Object.keys(options?.inlineOptions && typeof options.inlineOptions === "object" ? options.inlineOptions : {});
+    const unknownInlineOptionNames = inlineOptionNames.filter((optionName) => !supportedOptionNames.has(optionName));
+    if (unknownInlineOptionNames.length > 0) {
+      throw createCliError(
+        `Unknown option${unknownInlineOptionNames.length === 1 ? "" : "s"} for jskit app ${definition.name}: ${unknownInlineOptionNames.map((optionName) => `--${optionName}`).join(", ")}.`,
+        {
+          renderUsage: () => renderAppHelp(stderr, definition)
+        }
+      );
+    }
+    if (options?.dryRun === true && !supportedOptionNames.has("dry-run")) {
+      throw createCliError(`Unknown option for jskit app ${definition.name}: --dry-run.`, {
+        renderUsage: () => renderAppHelp(stderr, definition)
+      });
+    }
+
+    if (positional.length > 1) {
+      throw createCliError(`Unexpected positional arguments for jskit app ${definition.name}: ${positional.slice(1).join(" ")}`, {
+        renderUsage: () => renderAppHelp(stderr, definition)
+      });
+    }
+
+    if (definition.name === "verify") {
+      return runAppVerifyCommand(ctx, { appRoot, options, stdout, stderr });
+    }
+    if (definition.name === "update-packages") {
+      return runAppUpdatePackagesCommand(ctx, { appRoot, options, stdout, stderr });
+    }
+    if (definition.name === "link-local-packages") {
+      return runAppLinkLocalPackagesCommand(ctx, { appRoot, options, stdout, stderr });
+    }
+    if (definition.name === "release") {
+      return runAppReleaseCommand(ctx, { appRoot, options, stdout, stderr });
+    }
+    if (definition.name === "adopt-managed-scripts") {
+      return runAppAdoptManagedScriptsCommand(ctx, { appRoot, options, stdout, stderr });
+    }
+
+    throw createCliError(`Unhandled app subcommand: ${definition.name}.`, {
+      renderUsage: () => renderAppHelp(stderr, definition)
+    });
+  }
+
+  return {
+    commandApp
+  };
+}
+
+export { createAppCommands };

package/src/server/commandHandlers/appCommandCatalog.js

@@ -0,0 +1,170 @@
+const APP_SCRIPT_WRAPPERS = Object.freeze({
+  verify: "jskit app verify && npm run --if-present verify:app",
+  "jskit:update": "jskit app update-packages",
+  devlinks: "jskit app link-local-packages",
+  release: "jskit app release"
+});
+
+const LEGACY_APP_SCRIPT_VALUES = Object.freeze({
+  verify: Object.freeze([
+    "npm run lint && npm run test && npm run test:client && npm run build && npx jskit doctor"
+  ]),
+  "jskit:update": Object.freeze([
+    "bash ./scripts/update-jskit-packages.sh"
+  ]),
+  devlinks: Object.freeze([
+    "bash ./scripts/link-local-jskit-packages.sh"
+  ]),
+  release: Object.freeze([
+    "bash ./scripts/release.sh"
+  ])
+});
+
+const LEGACY_APP_SCRIPT_FILES = Object.freeze([
+  "scripts/update-jskit-packages.sh",
+  "scripts/link-local-jskit-packages.sh",
+  "scripts/release.sh"
+]);
+
+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([]),
+    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.",
+      "The scaffolded npm run verify wrapper can append npm run --if-present verify:app afterwards."
+    ])
+  }),
+  "update-packages": Object.freeze({
+    name: "update-packages",
+    summary: "Update installed @jskit-ai dependencies and refresh managed migrations.",
+    usage: "jskit app update-packages [--registry <url>] [--dry-run]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--registry <url>",
+        description: "Use a custom npm registry when resolving and installing @jskit-ai packages."
+      }),
+      Object.freeze({
+        label: "--dry-run",
+        description: "Show the npm install plan without mutating package.json, lockfiles, or migrations."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Runtime and dev @jskit-ai dependencies are updated separately so package.json sections stay correct.",
+      "Each package is moved to the latest available major.x range and npm saves the resolved exact version.",
+      "Managed migrations are refreshed afterwards unless --dry-run is used."
+    ])
+  }),
+  "link-local-packages": Object.freeze({
+    name: "link-local-packages",
+    summary: "Link local @jskit-ai workspace packages into the current app for live development.",
+    usage: "jskit app link-local-packages [--repo-root <path>]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--repo-root <path>",
+        description: "Explicit jskit-ai monorepo checkout to link from. If omitted, JSKIT_REPO_ROOT or nearby jskit-ai directories are used."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Links packages from both the monorepo packages/ and tooling/ directories.",
+      "Refreshes node_modules/.bin entries for linked packages that publish binaries.",
+      "Clears node_modules/.vite so Vite does not keep stale prebundled paths."
+    ])
+  }),
+  release: Object.freeze({
+    name: "release",
+    summary: "Run the JSKIT release helper for an app repository.",
+    usage: "jskit app release [--registry <url>] [--dry-run]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--registry <url>",
+        description: "Use a custom npm registry for the internal package-refresh step before opening a release PR."
+      }),
+      Object.freeze({
+        label: "--dry-run",
+        description: "Preview the release flow without syncing main, updating packages, or opening a PR."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Requires a clean worktree, the main branch, git, npm, and gh auth.",
+      "Syncs local main, runs jskit app update-packages, commits resulting changes, opens a PR, merges it, then re-syncs local main.",
+      "If update-packages produces no changes, release exits without opening a PR."
+    ])
+  }),
+  "adopt-managed-scripts": Object.freeze({
+    name: "adopt-managed-scripts",
+    summary: "Rewrite legacy scaffolded maintenance scripts to the modern jskit app wrappers.",
+    usage: "jskit app adopt-managed-scripts [--dry-run] [--force]",
+    options: Object.freeze([
+      Object.freeze({
+        label: "--dry-run",
+        description: "Preview the script rewrites without writing package.json."
+      }),
+      Object.freeze({
+        label: "--force",
+        description: "Replace customized script values too, and remove the legacy copied maintenance scripts if they exist."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Known scaffolded script values are rewritten automatically.",
+      "Customized script values are reported and left alone unless --force is used.",
+      "This command is the migration path for existing apps that still carry copied JSKIT maintenance scripts."
+    ])
+  })
+});
+
+function listAppCommandDefinitions() {
+  return Object.values(APP_COMMAND_DEFINITIONS)
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function resolveAppCommandDefinition(rawName = "") {
+  const normalizedName = String(rawName || "").trim();
+  if (!normalizedName) {
+    return null;
+  }
+  return APP_COMMAND_DEFINITIONS[normalizedName] || null;
+}
+
+function buildAppCommandOptionMeta(subcommandName = "") {
+  const definition = resolveAppCommandDefinition(subcommandName);
+  const optionMeta = {
+    help: { inputType: "flag" }
+  };
+
+  if (!definition) {
+    return optionMeta;
+  }
+
+  if (
+    definition.name === "update-packages" ||
+    definition.name === "adopt-managed-scripts" ||
+    definition.name === "release"
+  ) {
+    optionMeta["dry-run"] = { inputType: "flag" };
+  }
+  if (definition.name === "adopt-managed-scripts") {
+    optionMeta.force = { inputType: "flag" };
+  }
+  if (definition.name === "update-packages" || definition.name === "release") {
+    optionMeta.registry = { inputType: "text" };
+  }
+  if (definition.name === "link-local-packages") {
+    optionMeta["repo-root"] = { inputType: "text" };
+  }
+
+  return optionMeta;
+}
+
+export {
+  APP_SCRIPT_WRAPPERS,
+  LEGACY_APP_SCRIPT_VALUES,
+  LEGACY_APP_SCRIPT_FILES,
+  APP_COMMAND_DEFINITIONS,
+  listAppCommandDefinitions,
+  resolveAppCommandDefinition,
+  buildAppCommandOptionMeta
+};

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

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { rm } from "node:fs/promises";
+import {
+  APP_SCRIPT_WRAPPERS,
+  LEGACY_APP_SCRIPT_FILES,
+  LEGACY_APP_SCRIPT_VALUES
+} from "../appCommandCatalog.js";
+import { fileExists, isTruthyFlag } from "./shared.js";
+
+function shouldRewriteScript(currentValue = "", scriptName = "", force = false) {
+  const desiredValue = APP_SCRIPT_WRAPPERS[scriptName];
+  const normalizedCurrentValue = String(currentValue || "").trim();
+  if (!normalizedCurrentValue) {
+    return {
+      rewrite: true,
+      reason: "missing"
+    };
+  }
+  if (normalizedCurrentValue === desiredValue) {
+    return {
+      rewrite: false,
+      reason: "already-current"
+    };
+  }
+  if ((LEGACY_APP_SCRIPT_VALUES[scriptName] || []).includes(normalizedCurrentValue)) {
+    return {
+      rewrite: true,
+      reason: "legacy"
+    };
+  }
+  if (force) {
+    return {
+      rewrite: true,
+      reason: "force"
+    };
+  }
+  return {
+    rewrite: false,
+    reason: "customized"
+  };
+}
+
+async function runAppAdoptManagedScriptsCommand(ctx = {}, { appRoot = "", options = {}, stdout }) {
+  const {
+    loadAppPackageJson,
+    writeJsonFile
+  } = ctx;
+
+  const dryRun = options?.dryRun === true;
+  const force = isTruthyFlag(options?.inlineOptions?.force);
+  const {
+    packageJsonPath,
+    packageJson
+  } = await loadAppPackageJson(appRoot);
+
+  const packageJsonClone = JSON.parse(JSON.stringify(packageJson || {}));
+  const scripts = packageJsonClone.scripts && typeof packageJsonClone.scripts === "object"
+    ? packageJsonClone.scripts
+    : {};
+  packageJsonClone.scripts = scripts;
+
+  const changedScripts = [];
+  const skippedScripts = [];
+
+  for (const [scriptName, desiredValue] of Object.entries(APP_SCRIPT_WRAPPERS)) {
+    const currentValue = String(scripts[scriptName] || "");
+    const rewritePolicy = shouldRewriteScript(currentValue, scriptName, force);
+    if (!rewritePolicy.rewrite) {
+      if (rewritePolicy.reason === "customized") {
+        skippedScripts.push({
+          scriptName,
+          currentValue
+        });
+      }
+      continue;
+    }
+
+    scripts[scriptName] = desiredValue;
+    changedScripts.push({
+      scriptName,
+      previousValue: currentValue,
+      nextValue: desiredValue,
+      reason: rewritePolicy.reason
+    });
+  }
+
+  const removableLegacyFiles = [];
+  if (force) {
+    for (const relativePath of LEGACY_APP_SCRIPT_FILES) {
+      const absolutePath = path.join(appRoot, relativePath);
+      if (await fileExists(absolutePath)) {
+        removableLegacyFiles.push({
+          relativePath,
+          absolutePath
+        });
+      }
+    }
+  }
+
+  if (!dryRun && changedScripts.length > 0) {
+    await writeJsonFile(packageJsonPath, packageJsonClone);
+  }
+
+  if (!dryRun && force) {
+    for (const { absolutePath } of removableLegacyFiles) {
+      await rm(absolutePath, { recursive: true, force: true });
+    }
+  }
+
+  if (changedScripts.length < 1 && skippedScripts.length < 1 && removableLegacyFiles.length < 1) {
+    stdout.write("[adopt-managed-scripts] package.json already uses the managed JSKIT wrappers.\n");
+    return 0;
+  }
+
+  for (const record of changedScripts) {
+    stdout.write(`[adopt-managed-scripts] ${dryRun ? "would rewrite" : "rewrote"} script ${record.scriptName} (${record.reason}).\n`);
+  }
+  for (const record of skippedScripts) {
+    stdout.write(`[adopt-managed-scripts] kept customized script ${record.scriptName}: ${record.currentValue}\n`);
+  }
+  for (const record of removableLegacyFiles) {
+    stdout.write(`[adopt-managed-scripts] ${dryRun ? "would remove" : "removed"} ${record.relativePath}\n`);
+  }
+
+  if (skippedScripts.length > 0 && !force) {
+    stdout.write("[adopt-managed-scripts] rerun with --force to replace customized maintenance wrappers too.\n");
+  }
+
+  return 0;
+}
+
+export { runAppAdoptManagedScriptsCommand };

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

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { mkdir, rm, symlink } from "node:fs/promises";
+import {
+  discoverLocalPackageMap,
+  fileExists,
+  linkPackageBinEntries,
+  resolveLocalRepoRoot,
+  resolveSymlinkType
+} from "./shared.js";
+
+async function runAppLinkLocalPackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout }) {
+  const { createCliError } = ctx;
+  const explicitRepoRoot = String(options?.inlineOptions?.["repo-root"] || "").trim();
+  const scopeDirectory = path.join(appRoot, "node_modules", "@jskit-ai");
+  const viteCacheDirectory = path.join(appRoot, "node_modules", ".vite");
+
+  if (!(await fileExists(scopeDirectory))) {
+    throw createCliError(`[link-local] @jskit-ai scope not found at ${scopeDirectory} (run npm install first).`, {
+      exitCode: 1
+    });
+  }
+
+  const repoRoot = await resolveLocalRepoRoot({ appRoot, explicitRepoRoot });
+  if (!repoRoot) {
+    throw createCliError("[link-local] no JSKIT repository found. Set JSKIT_REPO_ROOT or use --repo-root.", {
+      exitCode: 1
+    });
+  }
+
+  if (!(await fileExists(path.join(repoRoot, "packages"))) || !(await fileExists(path.join(repoRoot, "tooling")))) {
+    throw createCliError(`[link-local] JSKIT repo root is not valid: ${repoRoot}`, {
+      exitCode: 1
+    });
+  }
+
+  const packageMap = await discoverLocalPackageMap(repoRoot);
+  let linkedCount = 0;
+  await mkdir(scopeDirectory, { recursive: true });
+
+  for (const [packageDirName, sourceDir] of [...packageMap.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
+    const targetPath = path.join(scopeDirectory, packageDirName);
+    await rm(targetPath, { recursive: true, force: true });
+    await symlink(sourceDir, targetPath, resolveSymlinkType());
+    stdout.write(`[link-local] linked @jskit-ai/${packageDirName} -> ${sourceDir}\n`);
+    await linkPackageBinEntries({
+      appRoot,
+      packageDirName,
+      sourceDir,
+      stdout
+    });
+    linkedCount += 1;
+  }
+
+  if (await fileExists(viteCacheDirectory)) {
+    await rm(viteCacheDirectory, { recursive: true, force: true });
+    stdout.write(`[link-local] cleared Vite cache at ${viteCacheDirectory}\n`);
+  }
+
+  stdout.write(`[link-local] done. linked=${linkedCount}\n`);
+  return 0;
+}
+
+export { runAppLinkLocalPackagesCommand };

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

@@ -0,0 +1,174 @@
+import { runAppUpdatePackagesCommand } from "./updatePackages.js";
+import {
+  formatUtcReleaseTimestamp,
+  runExternalCommand
+} from "./shared.js";
+
+async function runAppReleaseCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
+  const { createCliError } = ctx;
+
+  runExternalCommand("gh", ["auth", "status"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+
+  const worktreeStatus = runExternalCommand("git", ["status", "--porcelain"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+  if (String(worktreeStatus.stdout || "").trim()) {
+    throw createCliError("[release] worktree is not clean. Commit or stash changes first.", {
+      exitCode: 1
+    });
+  }
+
+  const branchResult = runExternalCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+  const currentBranch = String(branchResult.stdout || "").trim();
+  if (currentBranch !== "main") {
+    throw createCliError(`[release] current branch is "${currentBranch}". Switch to main first.`, {
+      exitCode: 1
+    });
+  }
+
+  if (options?.dryRun) {
+    stdout.write("[release] dry-run mode: would sync main, run jskit app update-packages, and open a PR if changes appear.\n");
+    return 0;
+  }
+
+  stdout.write("[release] syncing local main...\n");
+  runExternalCommand("git", ["fetch", "origin", "main"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  runExternalCommand("git", ["pull", "--ff-only", "origin", "main"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+
+  stdout.write("[release] running package refresh...\n");
+  const registryUrl = String(options?.inlineOptions?.registry || "").trim();
+  await runAppUpdatePackagesCommand(ctx, {
+    appRoot,
+    options: {
+      ...options,
+      dryRun: false,
+      inlineOptions: registryUrl
+        ? { registry: registryUrl }
+        : {}
+    },
+    stdout,
+    stderr
+  });
+
+  const postUpdateStatus = runExternalCommand("git", ["status", "--porcelain"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+  if (!String(postUpdateStatus.stdout || "").trim()) {
+    stdout.write("[release] no changes produced by jskit app update-packages. Nothing to release.\n");
+    return 0;
+  }
+
+  const { branchStamp, pretty } = formatUtcReleaseTimestamp();
+  const branchName = `release/${branchStamp}`;
+  const commitMessage = `chore: release ${pretty}`;
+  const prTitle = `Release ${pretty}`;
+  const prBody = "Automated release commit generated by `jskit app release`.";
+
+  stdout.write(`[release] creating branch ${branchName}...\n`);
+  runExternalCommand("git", ["switch", "-c", branchName], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  runExternalCommand("git", ["add", "-A"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  runExternalCommand("git", ["commit", "-m", commitMessage], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  runExternalCommand("git", ["push", "-u", "origin", branchName], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+
+  const prCreateResult = runExternalCommand("gh", [
+    "pr",
+    "create",
+    "--base",
+    "main",
+    "--head",
+    branchName,
+    "--title",
+    prTitle,
+    "--body",
+    prBody
+  ], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet: true,
+    createCliError
+  });
+  const prUrl = String(prCreateResult.stdout || "").trim();
+  if (!prUrl) {
+    throw createCliError("[release] gh pr create did not return a PR URL.", {
+      exitCode: 1
+    });
+  }
+
+  stdout.write(`[release] created PR: ${prUrl}\n`);
+  runExternalCommand("gh", ["pr", "merge", prUrl, "--merge", "--delete-branch"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+
+  stdout.write("[release] merged. syncing local main...\n");
+  runExternalCommand("git", ["switch", "main"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  runExternalCommand("git", ["pull", "--ff-only", "origin", "main"], {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    createCliError
+  });
+  stdout.write("[release] done.\n");
+
+  return 0;
+}
+
+export { runAppReleaseCommand };

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

@@ -0,0 +1,275 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { access, mkdir, readFile, readdir, rm, symlink } from "node:fs/promises";
+
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+async function fileExists(filePath = "") {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isTruthyFlag(rawValue = "") {
+  const normalizedValue = normalizeText(rawValue).toLowerCase();
+  return normalizedValue === "true" || normalizedValue === "1" || normalizedValue === "yes";
+}
+
+function ensureCommandSucceeded(result, label, { createCliError, cwd = "", stdout, stderr, quiet = false } = {}) {
+  if (!quiet) {
+    const capturedStdout = String(result?.stdout || "");
+    const capturedStderr = String(result?.stderr || "");
+    if (capturedStdout) {
+      stdout?.write(capturedStdout);
+    }
+    if (capturedStderr) {
+      stderr?.write(capturedStderr);
+    }
+  }
+
+  if (result?.error) {
+    if (result.error.code === "ENOENT") {
+      throw createCliError(`${label} is not available in PATH.`, {
+        exitCode: 1
+      });
+    }
+    throw result.error;
+  }
+
+  if (result?.status !== 0) {
+    const suffix = cwd ? ` (cwd: ${cwd})` : "";
+    throw createCliError(`${label} failed with exit code ${result?.status ?? 1}${suffix}.`, {
+      exitCode: Number.isInteger(result?.status) ? result.status : 1
+    });
+  }
+
+  return result;
+}
+
+function runExternalCommand(
+  command,
+  args = [],
+  {
+    cwd = "",
+    env = {},
+    stdout,
+    stderr,
+    quiet = false,
+    createCliError
+  } = {}
+) {
+  const result = spawnSync(command, Array.isArray(args) ? args : [], {
+    cwd: cwd || process.cwd(),
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ...env
+    }
+  });
+  return ensureCommandSucceeded(result, command, {
+    createCliError,
+    cwd,
+    stdout,
+    stderr,
+    quiet
+  });
+}
+
+function formatUtcReleaseTimestamp(date = new Date()) {
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(date.getUTCDate()).padStart(2, "0");
+  const hours = String(date.getUTCHours()).padStart(2, "0");
+  const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+  const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+
+  return {
+    branchStamp: `${year}${month}${day}-${hours}${minutes}${seconds}`,
+    pretty: `${year}-${month}-${day} ${hours}:${minutes} UTC`
+  };
+}
+
+function resolveLocalJskitBin(appRoot = "") {
+  const binName = process.platform === "win32" ? "jskit.cmd" : "jskit";
+  return path.join(appRoot, "node_modules", ".bin", binName);
+}
+
+async function runLocalJskit(
+  appRoot,
+  args = [],
+  {
+    stdout,
+    stderr,
+    createCliError,
+    quiet = false
+  } = {}
+) {
+  const localJskitBin = resolveLocalJskitBin(appRoot);
+  if (!(await fileExists(localJskitBin))) {
+    throw createCliError(`Local jskit binary not found at ${path.relative(appRoot, localJskitBin)}. Run npm install first.`, {
+      exitCode: 1
+    });
+  }
+
+  return runExternalCommand(localJskitBin, args, {
+    cwd: appRoot,
+    stdout,
+    stderr,
+    quiet,
+    createCliError
+  });
+}
+
+async function resolveLocalRepoRoot({ appRoot = "", explicitRepoRoot = "" } = {}) {
+  const explicit = normalizeText(explicitRepoRoot);
+  if (explicit) {
+    return explicit;
+  }
+
+  const envRepoRoot = normalizeText(process.env.JSKIT_REPO_ROOT);
+  if (envRepoRoot) {
+    return envRepoRoot;
+  }
+
+  let currentDirectory = path.dirname(appRoot);
+  while (true) {
+    const candidateRoot = path.join(currentDirectory, "jskit-ai");
+    if (await fileExists(path.join(candidateRoot, "packages")) && await fileExists(path.join(candidateRoot, "tooling"))) {
+      return candidateRoot;
+    }
+    const parentDirectory = path.dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return "";
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+
+async function discoverLocalPackageMap(repoRoot = "") {
+  const packageMap = new Map();
+  const parentDirectories = [
+    path.join(repoRoot, "packages"),
+    path.join(repoRoot, "tooling")
+  ];
+
+  for (const parentDirectory of parentDirectories) {
+    if (!(await fileExists(parentDirectory))) {
+      continue;
+    }
+
+    const entries = await readdir(parentDirectory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) {
+        continue;
+      }
+
+      const packageRoot = path.join(parentDirectory, entry.name);
+      const packageJsonPath = path.join(packageRoot, "package.json");
+      if (!(await fileExists(packageJsonPath))) {
+        continue;
+      }
+
+      let packageJson = {};
+      try {
+        packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+      } catch {
+        continue;
+      }
+
+      const packageId = normalizeText(packageJson?.name);
+      if (!packageId.startsWith("@jskit-ai/")) {
+        continue;
+      }
+
+      const packageDirName = packageId.slice("@jskit-ai/".length);
+      if (!packageDirName || packageDirName.includes("/")) {
+        continue;
+      }
+
+      if (!packageMap.has(packageDirName)) {
+        packageMap.set(packageDirName, packageRoot);
+      }
+    }
+  }
+
+  return packageMap;
+}
+
+async function linkPackageBinEntries({
+  appRoot,
+  packageDirName,
+  sourceDir,
+  stdout
+} = {}) {
+  const packageJsonPath = path.join(sourceDir, "package.json");
+  if (!(await fileExists(packageJsonPath))) {
+    return;
+  }
+
+  let packageJson = {};
+  try {
+    packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+  } catch {
+    return;
+  }
+
+  const rawBin = packageJson?.bin;
+  let binEntries = [];
+  if (typeof rawBin === "string") {
+    binEntries = [[packageDirName, rawBin]];
+  } else if (rawBin && typeof rawBin === "object" && !Array.isArray(rawBin)) {
+    binEntries = Object.entries(rawBin);
+  }
+
+  if (binEntries.length < 1) {
+    return;
+  }
+
+  const binDirectory = path.join(appRoot, "node_modules", ".bin");
+  const packageRoot = path.join(appRoot, "node_modules", "@jskit-ai", packageDirName);
+  await mkdir(binDirectory, { recursive: true });
+
+  for (const [rawBinName, rawBinTarget] of binEntries) {
+    const binName = normalizeText(rawBinName);
+    const binTarget = normalizeText(rawBinTarget);
+    if (!binName || !binTarget) {
+      continue;
+    }
+
+    const absoluteTarget = path.join(packageRoot, binTarget);
+    if (!(await fileExists(absoluteTarget))) {
+      continue;
+    }
+
+    const binPath = path.join(binDirectory, binName);
+    await rm(binPath, { recursive: true, force: true });
+    const relativeTarget = path.relative(binDirectory, absoluteTarget) || absoluteTarget;
+    await symlink(relativeTarget, binPath);
+    stdout?.write(`[link-local] linked bin ${binName} -> ${relativeTarget}\n`);
+  }
+}
+
+function resolveSymlinkType() {
+  return process.platform === "win32" ? "junction" : "dir";
+}
+
+export {
+  fileExists,
+  normalizeText,
+  isTruthyFlag,
+  runExternalCommand,
+  formatUtcReleaseTimestamp,
+  resolveLocalJskitBin,
+  runLocalJskit,
+  resolveLocalRepoRoot,
+  discoverLocalPackageMap,
+  linkPackageBinEntries,
+  resolveSymlinkType
+};

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

@@ -0,0 +1,102 @@
+import { runLocalJskit, runExternalCommand } from "./shared.js";
+
+function collectJskitPackageNames(packageMap = {}) {
+  return Object.keys(packageMap && typeof packageMap === "object" ? packageMap : {})
+    .filter((name) => String(name || "").startsWith("@jskit-ai/"))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function resolveMajorRangeFromVersion(packageName = "", rawVersion = "", createCliError) {
+  const normalizedVersion = String(rawVersion || "").trim();
+  const match = normalizedVersion.match(/^(\d+)\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?$/u);
+  if (!match) {
+    throw createCliError(`Invalid latest version for ${packageName}: ${normalizedVersion || "<empty>"}.`, {
+      exitCode: 1
+    });
+  }
+  return `${match[1]}.x`;
+}
+
+function resolveRegistryArgs(registryUrl = "") {
+  const normalizedRegistryUrl = String(registryUrl || "").trim();
+  if (!normalizedRegistryUrl) {
+    return [];
+  }
+  return ["--registry", normalizedRegistryUrl];
+}
+
+function resolveInstallSpecs(packageNames = [], resolveMajorRange) {
+  return packageNames.map((packageName) => `${packageName}@${resolveMajorRange(packageName)}`);
+}
+
+async function runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
+  const {
+    createCliError,
+    loadAppPackageJson
+  } = ctx;
+
+  const { packageJson } = await loadAppPackageJson(appRoot);
+  const runtimePackages = collectJskitPackageNames(packageJson?.dependencies);
+  const devPackages = collectJskitPackageNames(packageJson?.devDependencies);
+  const registryUrl = String(options?.inlineOptions?.registry || "").trim();
+  const registryArgs = resolveRegistryArgs(registryUrl);
+  const dryRun = options?.dryRun === true;
+
+  if (runtimePackages.length < 1 && devPackages.length < 1) {
+    stdout.write("[jskit:update] no @jskit-ai packages found in dependencies.\n");
+    return 0;
+  }
+
+  const resolveMajorRange = (packageName) => {
+    const result = runExternalCommand("npm", ["view", ...registryArgs, packageName, "version"], {
+      cwd: appRoot,
+      stdout,
+      stderr,
+      quiet: true,
+      createCliError
+    });
+    return resolveMajorRangeFromVersion(packageName, result.stdout, createCliError);
+  };
+
+  const runtimeSpecs = resolveInstallSpecs(runtimePackages, resolveMajorRange);
+  const devSpecs = resolveInstallSpecs(devPackages, resolveMajorRange);
+  const dryRunArgs = dryRun ? ["--dry-run"] : [];
+
+  if (dryRun) {
+    stdout.write("[jskit:update] dry-run mode enabled.\n");
+  }
+
+  if (runtimeSpecs.length > 0) {
+    stdout.write(`[jskit:update] updating runtime packages: ${runtimeSpecs.join(" ")}\n`);
+    runExternalCommand("npm", ["install", "--save-exact", ...registryArgs, ...dryRunArgs, ...runtimeSpecs], {
+      cwd: appRoot,
+      stdout,
+      stderr,
+      createCliError
+    });
+  }
+
+  if (devSpecs.length > 0) {
+    stdout.write(`[jskit:update] updating dev packages: ${devSpecs.join(" ")}\n`);
+    runExternalCommand("npm", ["install", "--save-dev", "--save-exact", ...registryArgs, ...dryRunArgs, ...devSpecs], {
+      cwd: appRoot,
+      stdout,
+      stderr,
+      createCliError
+    });
+  }
+
+  if (!dryRun) {
+    stdout.write("[jskit:update] generating managed migrations for changed packages.\n");
+    await runLocalJskit(appRoot, ["migrations", "changed"], {
+      stdout,
+      stderr,
+      createCliError
+    });
+  }
+
+  stdout.write("[jskit:update] done.\n");
+  return 0;
+}
+
+export { runAppUpdatePackagesCommand };

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

@@ -0,0 +1,35 @@
+import { runExternalCommand, runLocalJskit } from "./shared.js";
+
+const BASELINE_VERIFY_SCRIPTS = Object.freeze([
+  "lint",
+  "test",
+  "test:client",
+  "build"
+]);
+
+async function runAppVerifyCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr }) {
+  const { createCliError } = ctx;
+
+  if (options?.dryRun) {
+    throw createCliError("jskit app verify does not support --dry-run.", { exitCode: 1 });
+  }
+
+  for (const scriptName of BASELINE_VERIFY_SCRIPTS) {
+    runExternalCommand("npm", ["run", "--if-present", scriptName], {
+      cwd: appRoot,
+      stdout,
+      stderr,
+      createCliError
+    });
+  }
+
+  await runLocalJskit(appRoot, ["doctor"], {
+    stdout,
+    stderr,
+    createCliError
+  });
+
+  return 0;
+}
+
+export { runAppVerifyCommand };

package/src/server/core/commandCatalog.js

@@ -126,6 +126,47 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     inlineOptionMode: "enumerated",
     allowedValueOptionNames: Object.freeze(["scope", "package-id", "description"])
   }),
+  app: Object.freeze({
+    command: "app",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Run JSKIT-managed app maintenance helpers.",
+    minimalUse: "jskit app verify",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "<subcommand>",
+        description: "verify | update-packages | link-local-packages | release | adopt-managed-scripts."
+      })
+    ]),
+    defaults: Object.freeze([
+      "The scaffold keeps npm run shortcuts such as verify and jskit:update, but their maintained behavior lives under jskit app.",
+      "Use jskit app <subcommand> help for subcommand-specific usage.",
+      "--dry-run is accepted by update-packages, adopt-managed-scripts, and release."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Scaffolded maintenance shortcuts",
+        lines: Object.freeze([
+          "jskit app verify",
+          "jskit app update-packages"
+        ])
+      }),
+      Object.freeze({
+        label: "Existing app migration",
+        lines: Object.freeze([
+          "jskit app adopt-managed-scripts --dry-run",
+          "jskit app adopt-managed-scripts --force"
+        ])
+      })
+    ]),
+    fullUse: "jskit app <subcommand> [help] [--dry-run] [--<option> <value>...]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandApp",
+    allowedFlagKeys: Object.freeze(["dryRun"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
+  }),
   add: Object.freeze({
     command: "add",
     aliases: Object.freeze([]),

package/src/server/core/createCommandHandlers.js

@@ -2,6 +2,7 @@ import { createCommandHandlerShared } from "../commandHandlers/shared.js";
 import { createListCommands } from "../commandHandlers/list.js";
 import { createShowCommand } from "../commandHandlers/show.js";
 import { createPackageCommands } from "../commandHandlers/package.js";
+import { createAppCommands } from "../commandHandlers/app.js";
 import { createHealthCommands } from "../commandHandlers/health.js";
 import { createCompletionCommands } from "../commandHandlers/completion.js";
 
@@ -23,6 +24,7 @@ function createCommandHandlers(deps = {}) {
     commandPosition,
     commandRemove
   } = createPackageCommands(commandContext);
+  const { commandApp } = createAppCommands(commandContext);
   const { commandDoctor, commandLintDescriptors } = createHealthCommands(commandContext);
   const { commandCompletion } = createCompletionCommands(commandContext);
 
@@ -32,6 +34,7 @@ function createCommandHandlers(deps = {}) {
     commandListLinkItems,
     commandCompletion,
     commandShow,
+    commandApp,
     commandCreate,
     commandAdd,
     commandGenerate,