@jskit-ai/jskit-cli 0.2.80 → 0.2.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.80",
+  "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.79",
-    "@jskit-ai/kernel": "0.1.71",
-    "@jskit-ai/shell-web": "0.1.70"
+    "@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

@@ -4,6 +4,7 @@ import {
   adoptCodexThreadId,
   buildSessionErrorResponse,
   createSession,
+  inspectSessionDiff,
   inspectSessionDetails,
   listSessions,
   runSessionStep
@@ -52,6 +53,17 @@ function writeSessionText(stdout, payload) {
     stdout.write(payload.prompt);
     stdout.write("\n");
   }
+  if (payload.gitStatus !== undefined && payload.unstagedDiff !== undefined) {
+    stdout.write("\nGit status:\n");
+    stdout.write(payload.gitStatus || "No changes.");
+    stdout.write("\n");
+    const diff = [payload.stagedDiff, payload.unstagedDiff, payload.untrackedDiff].filter(Boolean).join("\n");
+    if (diff) {
+      stdout.write("\nDiff:\n");
+      stdout.write(diff);
+      stdout.write("\n");
+    }
+  }
   if (payload.errors?.length) {
     stdout.write("Errors:\n");
     for (const error of payload.errors) {
@@ -135,6 +147,34 @@ 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",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --issue-title "<title>" --issue -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "issue-title"
+  });
+  if (issueTitle.ok === false) {
+    return issueTitle;
+  }
+
   const issue = await resolveTextInput({
     codePrefix: "issue",
     fileOption: "issue-file",
@@ -150,18 +190,138 @@ async function resolveStepInputs({
     return issue;
   }
 
+  const plan = await resolveTextInput({
+    codePrefix: "plan",
+    fileOption: "plan-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --plan -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "plan"
+  });
+  if (plan.ok === false) {
+    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,
-    ok: true
+    issueTitle: issueTitle.value,
+    ok: true,
+    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 = {}) {
+  const archives = [];
+  if (options.abandoned) {
+    archives.push("abandoned");
+  }
+  if (options.completed) {
+    archives.push("completed");
+  }
+  if (options.all) {
+    archives.push("all");
+  }
+  return archives.length > 0 ? archives : "active";
 }
 
 function createSessionCommands() {
@@ -178,7 +338,10 @@ function createSessionCommands() {
       let payload;
 
       if (!first) {
-        payload = await listSessions({ targetRoot: cwd });
+        payload = await listSessions({
+          targetRoot: cwd,
+          archive: resolveListArchiveOption(options)
+        });
       } else if (first === "create") {
         payload = await createSession({ targetRoot: cwd });
       } else if (second === "step") {
@@ -195,7 +358,14 @@ function createSessionCommands() {
               sessionId: first,
               options: {
                 ...normalizeStepOptions(inlineOptions),
-                issue: stepInputs.issue
+                issue: stepInputs.issue,
+                issueTitle: stepInputs.issueTitle,
+                plan: stepInputs.plan,
+                issueDetails: stepInputs.issueDetails,
+                reworkNotes: stepInputs.reworkNotes,
+                skipReason: stepInputs.skipReason,
+                agentDecisions: stepInputs.agentDecisions,
+                closeReason: stepInputs.closeReason
               }
             });
       } else if (second === "abandon") {
@@ -203,6 +373,11 @@ function createSessionCommands() {
           targetRoot: cwd,
           sessionId: first
         });
+      } else if (second === "diff") {
+        payload = await inspectSessionDiff({
+          targetRoot: cwd,
+          sessionId: first
+        });
       } else if (second === "adopt-codex-thread") {
         payload = await adoptCodexThreadId({
           targetRoot: cwd,

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

@@ -23,6 +23,8 @@ function parseArgs(argv, { createCliError } = {}) {
         verbose: false,
         json: false,
         all: false,
+        abandoned: false,
+        completed: false,
         concrete: false,
         help: true,
         inlineOptions: {}
@@ -50,6 +52,8 @@ function parseArgs(argv, { createCliError } = {}) {
     verbose: false,
     json: false,
     all: false,
+    abandoned: false,
+    completed: false,
     concrete: false,
     help: false,
     inlineOptions: {}
@@ -109,6 +113,14 @@ function parseArgs(argv, { createCliError } = {}) {
       options.all = true;
       continue;
     }
+    if (token === "--abandoned") {
+      options.abandoned = true;
+      continue;
+    }
+    if (token === "--completed") {
+      options.completed = true;
+      continue;
+    }
     if (token === "--concrete") {
       options.concrete = true;
       continue;
@@ -125,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);