@jskit-ai/jskit-cli 0.2.81 → 0.2.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.81",
+  "version": "0.2.82",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,11 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.80",
-    "@jskit-ai/kernel": "0.1.72",
-    "@jskit-ai/shell-web": "0.1.71"
+    "@jskit-ai/jskit-catalog": "0.1.81",
+    "@jskit-ai/kernel": "0.1.73",
+    "@jskit-ai/shell-web": "0.1.72",
+    "@vue/compiler-sfc": "^3.5.29",
+    "ts-morph": "^28.0.0"
   },
   "engines": {
     "node": ">=20 <23"

package/src/server/appBlueprint.js

@@ -28,7 +28,7 @@ function resolveAppBlueprintPaths(targetRoot = process.cwd()) {
 function extractAppBlueprintText(value = "") {
   const text = normalizeText(value);
   const match = /\[app_blueprint\]([\s\S]*?)\[\/app_blueprint\]/u.exec(text);
-  return normalizeText(match ? match[1] : text);
+  return normalizeText(match ? match[1] : "");
 }
 
 async function readAppPromptTemplate(paths, templateName) {

package/src/server/commandHandlers/helperMap.js

@@ -0,0 +1,104 @@
+function writeJson(stdout, payload) {
+  stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function writeErrors(stdout, payload) {
+  for (const error of payload.errors || []) {
+    stdout.write(`[${error.code}] ${error.message}\n`);
+    if (error.repairCommand) {
+      stdout.write(`Repair: ${error.repairCommand}\n`);
+    }
+  }
+}
+
+function writeHelperMapText(stdout, payload) {
+  if (Object.hasOwn(payload, "changed")) {
+    stdout.write(
+      payload.changed
+        ? `Updated helper map at ${payload.helperMapMarkdownPath}.\n`
+        : `Helper map is up to date at ${payload.helperMapMarkdownPath}.\n`
+    );
+    return;
+  }
+  if (payload.exists === false) {
+    stdout.write(`No helper map set at ${payload.helperMapMarkdownPath}. Run jskit helper-map update.\n`);
+    return;
+  }
+  if (payload.markdown) {
+    stdout.write(payload.markdown);
+    return;
+  }
+  stdout.write(`Helper map is up to date at ${payload.helperMapMarkdownPath}.\n`);
+}
+
+function createHelperMapCommands(ctx = {}) {
+  const { resolveAppRootFromCwd } = ctx;
+
+  async function commandHelperMap({
+    positional = [],
+    options = {},
+    cwd,
+    stdout
+  } = {}) {
+    const subcommand = String(positional[0] || "").trim();
+    let payload;
+
+    try {
+      const appRoot = await resolveAppRootFromCwd(cwd);
+      if (positional.length > 1) {
+        payload = {
+          ok: false,
+          errors: [
+            {
+              code: "unexpected_helper_map_argument",
+              message: `Unexpected helper-map argument: ${positional.slice(1).join(" ")}`,
+              repairCommand: "jskit helper-map"
+            }
+          ]
+        };
+      } else if (!subcommand) {
+        const { readHelperMap } = await import("../helperMap.js");
+        payload = await readHelperMap({ targetRoot: appRoot });
+      } else if (subcommand === "update") {
+        const { updateHelperMap } = await import("../helperMap.js");
+        payload = await updateHelperMap({ targetRoot: appRoot });
+      } else {
+        payload = {
+          ok: false,
+          errors: [
+            {
+              code: "unknown_helper_map_subcommand",
+              message: `Unknown helper-map subcommand: ${subcommand}`,
+              repairCommand: "jskit helper-map update"
+            }
+          ]
+        };
+      }
+    } catch (error) {
+      payload = {
+        ok: false,
+        errors: [
+          {
+            code: "helper_map_failed",
+            message: String(error?.message || error),
+            repairCommand: "jskit helper-map update"
+          }
+        ]
+      };
+    }
+
+    if (options.json) {
+      writeJson(stdout, payload);
+    } else if (payload.ok === false) {
+      writeErrors(stdout, payload);
+    } else {
+      writeHelperMapText(stdout, payload);
+    }
+
+    return payload.ok === false ? 1 : 0;
+  }
+
+  return { commandHelperMap };
+}
+
+export { createHelperMapCommands };

package/src/server/commandHandlers/session.js

@@ -147,6 +147,19 @@ async function resolveStepInputs({
   cwd,
   sessionId
 }) {
+  if (Object.hasOwn(inlineOptions, "blueprint") || Object.hasOwn(inlineOptions, "blueprint-file")) {
+    return {
+      ok: false,
+      payload: buildSessionErrorResponse({
+        targetRoot: cwd,
+        sessionId,
+        code: "session_blueprint_input_removed",
+        message: "The session blueprint step no longer accepts --blueprint input. Run the step to get the Codex prompt, let Codex edit .jskit/APP_BLUEPRINT.md, then run the step again.",
+        repairCommand: `jskit session ${sessionId} step`
+      })
+    };
+  }
+
   const issueTitle = await resolveTextInput({
     codePrefix: "issue_title",
     fileOption: "issue-title-file",
@@ -192,20 +205,109 @@ async function resolveStepInputs({
     return plan;
   }
 
+  const issueDetails = await resolveTextInput({
+    codePrefix: "issue_details",
+    fileOption: "issue-details-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --issue-details -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "issue-details"
+  });
+  if (issueDetails.ok === false) {
+    return issueDetails;
+  }
+
+  const reworkNotes = await resolveTextInput({
+    codePrefix: "rework_notes",
+    fileOption: "rework-notes-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --user-check failed --rework-notes -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "rework-notes"
+  });
+  if (reworkNotes.ok === false) {
+    return reworkNotes;
+  }
+
+  const skipReason = await resolveTextInput({
+    codePrefix: "skip_reason",
+    fileOption: "skip-reason-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --skip-ui-check --skip-reason "<reason>"`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "skip-reason"
+  });
+  if (skipReason.ok === false) {
+    return skipReason;
+  }
+
+  const agentDecisions = await resolveTextInput({
+    codePrefix: "agent_decisions",
+    fileOption: "agent-decisions-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --agent-decisions -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "agent-decisions"
+  });
+  if (agentDecisions.ok === false) {
+    return agentDecisions;
+  }
+
+  const closeReason = await resolveTextInput({
+    codePrefix: "close_reason",
+    fileOption: "close-reason-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --close-without-merge --close-reason "<reason>"`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "close-reason"
+  });
+  if (closeReason.ok === false) {
+    return closeReason;
+  }
+
   return {
+    agentDecisions: agentDecisions.value,
+    closeReason: closeReason.value,
     issue: issue.value,
     issueTitle: issueTitle.value,
     ok: true,
-    plan: plan.value
+    plan: plan.value,
+    issueDetails: issueDetails.value,
+    reworkNotes: reworkNotes.value,
+    skipReason: skipReason.value
   };
 }
 
 function normalizeStepOptions(inlineOptions = {}) {
-  return {
+  const options = {
     ...inlineOptions,
+    closeWithoutMerge: inlineOptions["close-without-merge"] === "true" || inlineOptions.closeWithoutMerge === true,
+    mergePr: inlineOptions["merge-pr"] === "true" || inlineOptions.mergePr === true,
     prompt: inlineOptions.prompt,
+    reviewFindings: inlineOptions["review-findings"] || inlineOptions.reviewFindings,
+    skipUiCheck: inlineOptions["skip-ui-check"] === "true" || inlineOptions.skipUiCheck === true,
     userCheck: inlineOptions["user-check"] || inlineOptions.userCheck
   };
+  if (Object.hasOwn(inlineOptions, "review-findings-remaining") || Object.hasOwn(inlineOptions, "reviewFindingsRemaining")) {
+    options.reviewFindingsRemaining = inlineOptions["review-findings-remaining"] === "true" ||
+      inlineOptions.reviewFindingsRemaining === true;
+  }
+  return options;
 }
 
 function resolveListArchiveOption(options = {}) {
@@ -258,7 +360,12 @@ function createSessionCommands() {
                 ...normalizeStepOptions(inlineOptions),
                 issue: stepInputs.issue,
                 issueTitle: stepInputs.issueTitle,
-                plan: stepInputs.plan
+                plan: stepInputs.plan,
+                issueDetails: stepInputs.issueDetails,
+                reworkNotes: stepInputs.reworkNotes,
+                skipReason: stepInputs.skipReason,
+                agentDecisions: stepInputs.agentDecisions,
+                closeReason: stepInputs.closeReason
               }
             });
       } else if (second === "abandon") {

package/src/server/commandHandlers/show.js

@@ -12,10 +12,17 @@ function createShowCommand(ctx = {}) {
     createColorFormatter,
     resolveWrapWidth,
     writeWrappedItems,
+    normalizeRelativePath,
     normalizeRelativePosixPath,
+    resolveAppRootFromCwd,
     resolvePackageIdInput,
     loadPackageRegistry,
     loadBundleRegistry,
+    loadAppLocalPackageRegistry,
+    loadLockFile,
+    mergePackageRegistries,
+    path,
+    fileExists,
     inspectPackageOfferings,
     buildFileWriteGroups,
     listDeclaredCapabilities,
@@ -28,7 +35,149 @@ function createShowCommand(ctx = {}) {
     deriveProviderDisplayName
   } = ctx;
 
-  async function commandShow({ positional, options, stdout }) {
+  async function renderPackageEntry({
+    packageRegistry,
+    packageEntry,
+    options,
+    stdout,
+    color
+  }) {
+    const {
+      payload,
+      provides,
+      requires,
+      capabilityDetails
+    } = await buildPackageShowPayload({
+      packageRegistry,
+      packageEntry,
+      options,
+      inspectPackageOfferings,
+      buildFileWriteGroups,
+      listDeclaredCapabilities,
+      buildCapabilityDetailsForPackage
+    });
+
+    if (options.json) {
+      stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    } else {
+      renderPackagePayloadText({
+        payload,
+        provides,
+        requires,
+        capabilityDetails,
+        options,
+        stdout,
+        color,
+        resolveWrapWidth,
+        writeWrappedItems,
+        normalizeRelativePosixPath,
+        formatPackageSubpathImport,
+        normalizePlacementOutlets,
+        normalizePlacementContributions,
+        shouldShowPackageExportTarget,
+        classifyExportedSymbols,
+        deriveProviderDisplayName
+      });
+    }
+  }
+
+  function isLocalPackageLockEntry(lockEntry = {}) {
+    const sourceType = String(lockEntry?.source?.type || "").trim();
+    return sourceType === "local-package" || sourceType === "app-local-package";
+  }
+
+  function resolveInstalledLocalPackageEntry(lock = {}, id = "") {
+    const normalizedId = String(id || "").trim();
+    if (!normalizedId) {
+      return null;
+    }
+
+    const installedPackages = lock?.installedPackages || {};
+    const directEntry = installedPackages[normalizedId];
+    if (directEntry && isLocalPackageLockEntry(directEntry)) {
+      return {
+        packageId: normalizedId,
+        lockEntry: directEntry
+      };
+    }
+
+    for (const [packageId, lockEntry] of Object.entries(installedPackages)) {
+      if (!isLocalPackageLockEntry(lockEntry)) {
+        continue;
+      }
+      const recordedPackageId = String(lockEntry?.packageId || "").trim();
+      if (recordedPackageId === normalizedId) {
+        return {
+          packageId,
+          lockEntry
+        };
+      }
+    }
+
+    return null;
+  }
+
+  async function assertInstalledLocalPackageIsDiscoverable({ appRoot, id }) {
+    const { lock } = await loadLockFile(appRoot);
+    const installedLocalPackage = resolveInstalledLocalPackageEntry(lock, id);
+    if (!installedLocalPackage) {
+      return;
+    }
+
+    const { packageId, lockEntry } = installedLocalPackage;
+    const source = lockEntry?.source || {};
+    const descriptorPath = String(source.descriptorPath || "").trim();
+    if (!descriptorPath) {
+      throw createCliError(
+        `Local package ${packageId} is recorded in .jskit/lock.json but has no descriptorPath.`
+      );
+    }
+
+    const absoluteDescriptorPath = path.resolve(appRoot, descriptorPath);
+    if (!(await fileExists(absoluteDescriptorPath))) {
+      throw createCliError(
+        `Local package ${packageId} is recorded in .jskit/lock.json but descriptor is missing at ${descriptorPath}.`
+      );
+    }
+
+    const packagePath = String(source.packagePath || "").trim();
+    if (packagePath) {
+      const packageJsonPath = path.join(appRoot, packagePath, "package.json");
+      if (!(await fileExists(packageJsonPath))) {
+        throw createCliError(
+          `Local package ${packageId} is recorded in .jskit/lock.json but package.json is missing at ${packagePath}/package.json.`
+        );
+      }
+    }
+
+    const descriptorLabel = normalizeRelativePath(appRoot, absoluteDescriptorPath);
+    throw createCliError(
+      `Local package ${packageId} is recorded in .jskit/lock.json but was not discoverable from ${descriptorLabel}. Ensure its package.json name matches the descriptor packageId.`
+    );
+  }
+
+  async function resolveAppLocalShowTarget({ id, cwd, catalogPackageRegistry }) {
+    let appRoot = "";
+    try {
+      appRoot = await resolveAppRootFromCwd(cwd);
+    } catch {
+      return null;
+    }
+
+    const appLocalRegistry = await loadAppLocalPackageRegistry(appRoot);
+    const resolvedPackageId = resolvePackageIdInput(id, appLocalRegistry);
+    if (resolvedPackageId) {
+      return {
+        packageRegistry: mergePackageRegistries(catalogPackageRegistry, appLocalRegistry),
+        packageEntry: appLocalRegistry.get(resolvedPackageId)
+      };
+    }
+
+    await assertInstalledLocalPackageIsDiscoverable({ appRoot, id });
+    return null;
+  }
+
+  async function commandShow({ positional, options, cwd, stdout }) {
     const id = String(positional[0] || "").trim();
     if (!id) {
       throw createCliError("show requires an id.", { showUsage: true });
@@ -41,43 +190,13 @@ function createShowCommand(ctx = {}) {
 
     if (resolvedPackageId) {
       const packageEntry = packageRegistry.get(resolvedPackageId);
-      const {
-        payload,
-        provides,
-        requires,
-        capabilityDetails
-      } = await buildPackageShowPayload({
+      await renderPackageEntry({
         packageRegistry,
         packageEntry,
         options,
-        inspectPackageOfferings,
-        buildFileWriteGroups,
-        listDeclaredCapabilities,
-        buildCapabilityDetailsForPackage
+        stdout,
+        color
       });
-
-      if (options.json) {
-        stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
-      } else {
-        renderPackagePayloadText({
-          payload,
-          provides,
-          requires,
-          capabilityDetails,
-          options,
-          stdout,
-          color,
-          resolveWrapWidth,
-          writeWrappedItems,
-          normalizeRelativePosixPath,
-          formatPackageSubpathImport,
-          normalizePlacementOutlets,
-          normalizePlacementContributions,
-          shouldShowPackageExportTarget,
-          classifyExportedSymbols,
-          deriveProviderDisplayName
-        });
-      }
       return 0;
     }
 
@@ -103,6 +222,22 @@ function createShowCommand(ctx = {}) {
       return 0;
     }
 
+    const appLocalTarget = await resolveAppLocalShowTarget({
+      id,
+      cwd,
+      catalogPackageRegistry: packageRegistry
+    });
+    if (appLocalTarget) {
+      await renderPackageEntry({
+        packageRegistry: appLocalTarget.packageRegistry,
+        packageEntry: appLocalTarget.packageEntry,
+        options,
+        stdout,
+        color
+      });
+      return 0;
+    }
+
     throw createCliError(`Unknown package or bundle: ${id}`);
   }
 

package/src/server/core/argParser.js

@@ -137,6 +137,14 @@ function parseArgs(argv, { createCliError } = {}) {
       options.inlineOptions.install = "true";
       continue;
     }
+    if (token === "--skip-ui-check") {
+      options.inlineOptions["skip-ui-check"] = "true";
+      continue;
+    }
+    if (token === "--close-without-merge") {
+      options.inlineOptions["close-without-merge"] = "true";
+      continue;
+    }
 
     if (token.startsWith("--")) {
       const withoutPrefix = token.slice(2);

package/src/server/core/commandCatalog.js

@@ -224,7 +224,16 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "Use --json for the stable machine-readable contract consumed by JSKIT AI Studio.",
       "Use --issue - to read approved issue body from stdin.",
       "Use --issue-title when the approved issue title is separate from the body.",
-      "Use --plan - to read the approved implementation plan from stdin."
+      "Use --issue-details - to read confirmed issue details from stdin.",
+      "Use --plan - to read the approved implementation plan from stdin.",
+      "Use --rework-notes - with --user-check failed to start the next plan cycle.",
+      "Use --agent-decisions - to append session-local decision log entries from implementation, UI review, verification, or repair phases.",
+      "Use --review-findings-remaining true --review-findings \"<findings>\" when an accepted review pass needs another pass.",
+      "Use --review-findings-remaining false only when the review/deslop loop is done.",
+      "Use --skip-ui-check --skip-reason \"<reason>\" only when uiImpact is possible and the Deep UI Check is intentionally skipped.",
+      "Use --merge-pr true at PR finalization to merge the pull request.",
+      "Use --close-without-merge --close-reason \"<reason>\" at PR finalization to complete the session without merging.",
+      "Run the blueprint step once to render its Codex prompt, then again after Codex updates .jskit/APP_BLUEPRINT.md."
     ]),
     examples: Object.freeze([
       Object.freeze({
@@ -234,13 +243,22 @@ const COMMAND_DESCRIPTORS = Object.freeze({
           "jskit session 2026-05-11_21-42-08 step",
           "jskit session 2026-05-11_21-42-08 step --prompt \"Fix the customer filters\"",
           "jskit session 2026-05-11_21-42-08 step --issue-title \"Fix customer filters\" --issue -",
+          "jskit session 2026-05-11_21-42-08 step --issue-details -",
           "jskit session 2026-05-11_21-42-08 step --plan -",
+          "jskit session 2026-05-11_21-42-08 step --agent-decisions -",
+          "jskit session 2026-05-11_21-42-08 step --review-findings-remaining true --review-findings \"A helper duplication fix needs another pass\"",
+          "jskit session 2026-05-11_21-42-08 step --review-findings-remaining false",
+          "jskit session 2026-05-11_21-42-08 step --skip-ui-check --skip-reason \"No user-facing UI changes\"",
+          "jskit session 2026-05-11_21-42-08 step",
+          "jskit session 2026-05-11_21-42-08 step --merge-pr true",
+          "jskit session 2026-05-11_21-42-08 step --close-without-merge --close-reason \"Prototype kept for reference\"",
+          "jskit session 2026-05-11_21-42-08 step --user-check failed --rework-notes -",
           "jskit session 2026-05-11_21-42-08 diff --json"
         ])
       })
     ]),
     fullUse:
-      "jskit session [create|<sessionId>] [step|diff|abandon|adopt-codex-thread] [--prompt <text>] [--issue-title <text>|--issue-title-file <path>] [--issue <text>|--issue-file <path>] [--plan <text>|--plan-file <path>] [--user-check <passed|failed>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
+      "jskit session [create|<sessionId>] [step|diff|abandon|adopt-codex-thread] [--prompt <text>] [--issue-title <text>|--issue-title-file <path>] [--issue <text>|--issue-file <path>] [--issue-details <text>|--issue-details-file <path>] [--plan <text>|--plan-file <path>] [--agent-decisions <text>|--agent-decisions-file <path>] [--review-findings-remaining true --review-findings <text>|--review-findings-remaining false] [--skip-ui-check --skip-reason <text>] [--merge-pr true|--close-without-merge --close-reason <text>] [--user-check <passed|failed>] [--rework-notes <text>|--rework-notes-file <path>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandSession",
     allowedFlagKeys: Object.freeze(["json", "abandoned", "completed", "all"]),
@@ -288,6 +306,44 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       return subcommand === "prompt" || subcommand === "set";
     }
   }),
+  "helper-map": Object.freeze({
+    command: "helper-map",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Read or update the generated app helper map.",
+    minimalUse: "jskit helper-map update",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "[update]",
+        description: "Without a subcommand, prints the saved helper map. update refreshes .jskit/helper-map files."
+      })
+    ]),
+    defaults: Object.freeze([
+      "The helper map is generated app state, not a hand-maintained workflow file.",
+      "The JSON file lives at .jskit/helper-map.json and the readable map lives at .jskit/helper-map.md.",
+      "Use the map before adding helpers, composables, service functions, maps, or package glue.",
+      "Use --json for a stable machine-readable response."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Refresh helper map",
+        lines: Object.freeze([
+          "jskit helper-map update",
+          "jskit helper-map --json"
+        ])
+      })
+    ]),
+    fullUse: "jskit helper-map [update] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandHelperMap",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => {
+      const subcommand = String(Array.isArray(positional) ? positional[0] || "" : "").trim();
+      return subcommand === "update";
+    }
+  }),
   add: Object.freeze({
     command: "add",
     aliases: Object.freeze([]),

package/src/server/core/createCommandHandlers.js

@@ -8,6 +8,7 @@ import { createHealthCommands } from "../commandHandlers/health.js";
 import { createCompletionCommands } from "../commandHandlers/completion.js";
 import { createSessionCommands } from "../commandHandlers/session.js";
 import { createBlueprintCommands } from "../commandHandlers/blueprint.js";
+import { createHelperMapCommands } from "../commandHandlers/helperMap.js";
 
 function createCommandHandlers(deps = {}) {
   const shared = createCommandHandlerShared(deps);
@@ -33,6 +34,7 @@ function createCommandHandlers(deps = {}) {
   const { commandCompletion } = createCompletionCommands(commandContext);
   const { commandSession } = createSessionCommands(commandContext);
   const { commandBlueprint } = createBlueprintCommands(commandContext);
+  const { commandHelperMap } = createHelperMapCommands(commandContext);
 
   return {
     commandList,
@@ -52,7 +54,8 @@ function createCommandHandlers(deps = {}) {
     commandDoctor,
     commandLintDescriptors,
     commandSession,
-    commandBlueprint
+    commandBlueprint,
+    commandHelperMap
   };
 }