@jskit-ai/jskit-cli 0.2.88 → 0.2.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.88",
+  "version": "0.2.90",
   "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.87",
-    "@jskit-ai/kernel": "0.1.79",
-    "@jskit-ai/shell-web": "0.1.78",
+    "@jskit-ai/jskit-catalog": "0.1.89",
+    "@jskit-ai/kernel": "0.1.81",
+    "@jskit-ai/shell-web": "0.1.80",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/commandHandlers/session.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import {
   abandonSession,
+  advanceSessionStep,
   adoptCodexThreadId,
   buildSessionErrorResponse,
   createSession,
@@ -8,7 +9,8 @@ import {
   inspectSessionDetails,
   listSessions,
   rewindSession,
-  runSessionStep
+  runSessionStep,
+  runSessionStepAction
 } from "../sessionRuntime.js";
 
 function writeJson(stdout, payload) {
@@ -77,6 +79,12 @@ function writeSessionText(stdout, payload) {
   if (payload.nextCommand) {
     stdout.write(`Next: ${payload.nextCommand}\n`);
   }
+  if (payload.actionCommands?.length) {
+    stdout.write("Available commands:\n");
+    for (const command of payload.actionCommands) {
+      stdout.write(`- ${command.command}\n`);
+    }
+  }
 }
 
 async function readStream(stream) {
@@ -161,66 +169,6 @@ async function resolveStepInputs({
     };
   }
 
-  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",
-    inlineOptions,
-    io,
-    repairCommand: `jskit session ${sessionId} step --issue -`,
-    cwd,
-    sessionId,
-    stdinOption: "-",
-    textOption: "issue"
-  });
-  if (issue.ok === false) {
-    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",
@@ -241,7 +189,7 @@ async function resolveStepInputs({
     fileOption: "skip-reason-file",
     inlineOptions,
     io,
-    repairCommand: `jskit session ${sessionId} step --skip-ui-check --skip-reason "<reason>"`,
+    repairCommand: `jskit session ${sessionId} skip --skip-reason "<reason>"`,
     cwd,
     sessionId,
     stdinOption: "-",
@@ -251,60 +199,8 @@ async function resolveStepInputs({
     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 --skip-merge --close-reason "<reason>"`,
-    cwd,
-    sessionId,
-    stdinOption: "-",
-    textOption: "close-reason"
-  });
-  if (closeReason.ok === false) {
-    return closeReason;
-  }
-
-  const codexResult = await resolveTextInput({
-    codePrefix: "codex_result",
-    fileOption: "codex-result-file",
-    inlineOptions,
-    io,
-    repairCommand: `jskit session ${sessionId} step --codex-result -`,
-    cwd,
-    sessionId,
-    stdinOption: "-",
-    textOption: "codex-result"
-  });
-  if (codexResult.ok === false) {
-    return codexResult;
-  }
-
   return {
-    agentDecisions: agentDecisions.value,
-    closeReason: closeReason.value,
-    codexResult: codexResult.value,
-    issue: issue.value,
-    issueTitle: issueTitle.value,
     ok: true,
-    plan: plan.value,
-    issueDetails: issueDetails.value,
     reworkNotes: reworkNotes.value,
     skipReason: skipReason.value
   };
@@ -313,15 +209,14 @@ async function resolveStepInputs({
 function normalizeStepOptions(inlineOptions = {}) {
   const options = {
     ...inlineOptions,
-    closeWithoutMerge: inlineOptions["close-without-merge"] === "true" ||
-      inlineOptions.closeWithoutMerge === true ||
-      inlineOptions["skip-merge"] === "true" ||
-      inlineOptions.skipMerge === true,
     mergePr: inlineOptions["merge-pr"] === "true" || inlineOptions.mergePr === true,
     prompt: inlineOptions.prompt,
     reviewFindings: inlineOptions["review-findings"] || inlineOptions.reviewFindings,
-    skipMainSync: inlineOptions["skip-main-sync"] === "true" || inlineOptions.skipMainSync === true,
-    skipUiCheck: inlineOptions["skip-ui-check"] === "true" || inlineOptions.skipUiCheck === true,
+    resolveDeslop: inlineOptions["resolve-deslop"] === "true" || inlineOptions.resolveDeslop === true,
+    skipStep: inlineOptions["skip-step"] === "true" ||
+      inlineOptions.skipStep === true ||
+      inlineOptions.skip === true ||
+      inlineOptions.skip === "true",
     userCheck: inlineOptions["user-check"] || inlineOptions.userCheck
   };
   if (Object.hasOwn(inlineOptions, "review-findings-remaining") || Object.hasOwn(inlineOptions, "reviewFindingsRemaining")) {
@@ -345,6 +240,96 @@ function resolveListArchiveOption(options = {}) {
   return archives.length > 0 ? archives : "active";
 }
 
+async function runSessionStepCommand({
+  cwd,
+  inlineOptions = {},
+  io = {},
+  sessionId
+}) {
+  const stepInputs = await resolveStepInputs({
+    inlineOptions,
+    io,
+    cwd,
+    sessionId
+  });
+  return stepInputs.ok === false
+    ? stepInputs.payload
+    : runSessionStep({
+        targetRoot: cwd,
+        sessionId,
+        options: {
+          ...normalizeStepOptions(inlineOptions),
+          reworkNotes: stepInputs.reworkNotes,
+          skipReason: stepInputs.skipReason
+        }
+      });
+}
+
+async function runNextSessionStep({
+  cwd,
+  sessionId
+}) {
+  return advanceSessionStep({
+    targetRoot: cwd,
+    sessionId
+  });
+}
+
+async function runSkipSessionStep({
+  cwd,
+  inlineOptions = {},
+  io = {},
+  sessionId
+}) {
+  return runSessionStepCommand({
+    cwd,
+    inlineOptions: {
+      ...inlineOptions,
+      skipStep: true
+    },
+    io,
+    sessionId
+  });
+}
+
+async function runDeslopSessionStep({
+  cwd,
+  sessionId
+}) {
+  const details = await inspectSessionDetails({
+    targetRoot: cwd,
+    sessionId
+  });
+  if (details.ok === false) {
+    return details;
+  }
+  if (details.currentStep === "review_changes_accepted") {
+    const accepted = await runSessionStep({
+      targetRoot: cwd,
+      sessionId,
+      options: {
+        reviewFindingsRemaining: true
+      }
+    });
+    if (accepted.ok === false) {
+      return accepted;
+    }
+  } else if (details.currentStep !== "review_prompt_rendered") {
+    return buildSessionErrorResponse({
+      targetRoot: cwd,
+      sessionId,
+      code: "deslop_not_current_step",
+      message: `Cannot run deslop while current step is ${details.currentStep || "done"}.`,
+      repairCommand: `jskit session ${sessionId}`
+    });
+  }
+  return runSessionStep({
+    targetRoot: cwd,
+    sessionId,
+    options: {}
+  });
+}
+
 function createSessionCommands() {
   return {
     async commandSession({
@@ -354,7 +339,7 @@ function createSessionCommands() {
       stdout,
       io = {}
     } = {}) {
-      const [first, second] = positional;
+      const [first, second, third] = positional;
       const inlineOptions = options.inlineOptions || {};
       let payload;
 
@@ -363,33 +348,79 @@ function createSessionCommands() {
           targetRoot: cwd,
           archive: resolveListArchiveOption(options)
         });
-      } else if (first === "create") {
+      } else if (first === "create" || first === "new") {
         payload = await createSession({ targetRoot: cwd });
       } else if (second === "step") {
-        const stepInputs = await resolveStepInputs({
+        payload = await inspectSessionDetails({
+          targetRoot: cwd,
+          sessionId: first
+        });
+      } else if (second === "run") {
+        const details = await inspectSessionDetails({
+          targetRoot: cwd,
+          sessionId: first
+        });
+        payload = {
+          ...details,
+          ok: false,
+          errors: [
+            {
+              code: "explicit_session_action_required",
+              message: "Generic run is not a session action. Use one of the available step commands, then run next."
+            }
+          ]
+        };
+      } else if ([
+        "create_worktree",
+        "run_npm_install",
+        "define_issue",
+        "create_issue_file",
+        "create_issue_on_gh",
+        "make_plan",
+        "execute_plan",
+        "run_deep_ui_check",
+        "run_automated_checks",
+        "update_blueprint",
+        "commit_changes",
+        "create_pull_request_file",
+        "create_pr_on_gh",
+        "prepare_for_merge",
+        "merge_pr",
+        "sync_main_checkout",
+        "finish_session"
+      ].includes(second)) {
+        payload = await runSessionStepAction({
+          action: second,
+          targetRoot: cwd,
+          sessionId: first,
+          options: normalizeStepOptions(inlineOptions)
+        });
+      } else if (second === "next") {
+        payload = await runNextSessionStep({
+          cwd,
+          sessionId: first
+        });
+      } else if (second === "skip") {
+        payload = await runSkipSessionStep({
+          cwd,
           inlineOptions,
           io,
+          sessionId: first
+        });
+      } else if (second === "deslop") {
+        payload = await runDeslopSessionStep({
           cwd,
           sessionId: first
         });
-        payload = stepInputs.ok === false
-          ? stepInputs.payload
-          : await runSessionStep({
-              targetRoot: cwd,
-              sessionId: first,
-              options: {
-                ...normalizeStepOptions(inlineOptions),
-                issue: stepInputs.issue,
-                issueTitle: stepInputs.issueTitle,
-                plan: stepInputs.plan,
-                issueDetails: stepInputs.issueDetails,
-                reworkNotes: stepInputs.reworkNotes,
-                skipReason: stepInputs.skipReason,
-                agentDecisions: stepInputs.agentDecisions,
-                closeReason: stepInputs.closeReason,
-                codexResult: stepInputs.codexResult
-              }
-            });
+      } else if (second === "resolve-deslop") {
+        payload = await runSessionStepAction({
+          action: "resolve_deslop",
+          targetRoot: cwd,
+          sessionId: first,
+          options: {
+            resolveDeslop: true
+          }
+        });
       } else if (second === "abandon") {
         payload = await abandonSession({
           targetRoot: cwd,
@@ -404,7 +435,7 @@ function createSessionCommands() {
         payload = await rewindSession({
           targetRoot: cwd,
           sessionId: first,
-          stepId: inlineOptions.step
+          stepId: inlineOptions.step || third
         });
       } else if (second === "adopt-codex-thread") {
         payload = await adoptCodexThreadId({

package/src/server/core/argParser.js

@@ -137,10 +137,6 @@ 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;

package/src/server/core/commandCatalog.js

@@ -212,8 +212,8 @@ const COMMAND_DESCRIPTORS = Object.freeze({
         description: "Create a session, inspect a session, or run a session subcommand."
       }),
       Object.freeze({
-        name: "[step|diff|rewind|abandon|adopt-codex-thread]",
-        description: "Run the next step, inspect a diff, rewind a session, abandon a session, or attach a Codex thread id."
+        name: "[step|create_worktree|run_npm_install|define_issue|create_issue_file|create_issue_on_gh|make_plan|execute_plan|run_deep_ui_check|run_automated_checks|update_blueprint|commit_changes|create_pull_request_file|create_pr_on_gh|prepare_for_merge|merge_pr|sync_main_checkout|finish_session|next|skip|deslop|resolve-deslop|diff|rewind|abandon|adopt-codex-thread]",
+        description: "Inspect, run an explicit step command, continue, skip, deslop, inspect a diff, rewind, abandon, or attach a Codex thread id."
       })
     ]),
     defaults: Object.freeze([
@@ -222,22 +222,22 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "The session id is timestamp-based and is the primary key.",
       "Bare list output includes active sessions only; use --abandoned, --completed, or --all for archived sessions.",
       "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 --issue-details - to read confirmed issue details from stdin.",
-      "Use --plan - to read the approved implementation plan from stdin.",
-      "Use --codex-result - after Codex prompt steps to read the final marked Codex result from stdin.",
-      "Use rewind --step <step_id> to delete a completed step and later JSKIT-owned session artifacts; only plan_made is allowed inside the repeatable cycle.",
-      "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 --prepare-merge true at PR merge preparation to render the Codex prep prompt.",
-      "Use --continue-to-merge true when the user decides to advance from preparation to merge decision.",
-      "Use --merge-pr true at PR finalization to merge the pull request.",
-      "Use --skip-merge at PR finalization to complete the session without merging.",
-      "Use --skip-main-sync at Main checkout synced to explicitly leave the main checkout untouched.",
+      "Issue handoff is file-based: Codex writes issue.md under the session root, then the user runs next. Plans stay in the terminal.",
+      "Use step to inspect the current step without running its work.",
+      "Use explicit step commands such as create_worktree, run_npm_install, define_issue, create_issue_file, create_issue_on_gh, make_plan, execute_plan, run_deep_ui_check, run_automated_checks, update_blueprint, commit_changes, create_pull_request_file, create_pr_on_gh, prepare_for_merge, merge_pr, sync_main_checkout, and finish_session to do the current step's work.",
+      "Use next to move to the next step after the current step's required work/result exists.",
+      "Use skip to record the current step as skipped and move to the next step.",
+      "Use deslop to run the review/deslop prompt from either review/deslop step.",
+      "Use resolve-deslop to send the explicit resolve review/deslop prompt. Nothing advances automatically afterward.",
+      "Use rewind <step_id> or rewind --step <step_id> to delete a completed step and later JSKIT-owned session artifacts.",
+      "Use --rework-notes - with --user-check failed to stay on user check and decide where to rewind.",
+      "Use deslop instead of hand-writing --review-findings-remaining true.",
+      "Use next instead of hand-writing --review-findings-remaining false.",
+      "Use skip --skip-reason \"<reason>\" when a step is intentionally skipped.",
+      "Use prepare_for_merge at Merge PR to render the Codex prep prompt.",
+      "Use merge_pr at Merge PR to attempt the GitHub merge.",
+      "Use sync_main_checkout at Sync main checkout after a successful merge.",
+      "Use finish_session at Congratulations! to archive the completed session.",
       "Run the blueprint step once to render its Codex prompt, then again after Codex updates .jskit/APP_BLUEPRINT.md."
     ]),
     examples: Object.freeze([
@@ -246,29 +246,41 @@ const COMMAND_DESCRIPTORS = Object.freeze({
         lines: Object.freeze([
           "jskit session create",
           "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 --codex-result -",
-          "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 --prepare-merge true",
-          "jskit session 2026-05-11_21-42-08 step --continue-to-merge true",
-          "jskit session 2026-05-11_21-42-08 step --merge-pr true",
-          "jskit session 2026-05-11_21-42-08 step --skip-merge",
-          "jskit session 2026-05-11_21-42-08 step --skip-main-sync",
+          "jskit session 2026-05-11_21-42-08 create_worktree",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 run_npm_install",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 define_issue --prompt \"Fix the customer filters\"",
+          "jskit session 2026-05-11_21-42-08 skip --skip-reason \"Handled outside JSKIT\"",
+          "jskit session 2026-05-11_21-42-08 create_issue_file",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 create_issue_on_gh",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 make_plan",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 execute_plan",
+          "jskit session 2026-05-11_21-42-08 deslop",
+          "jskit session 2026-05-11_21-42-08 resolve-deslop",
+          "jskit session 2026-05-11_21-42-08 commit_changes",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 create_pull_request_file",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 create_pr_on_gh",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 prepare_for_merge",
+          "jskit session 2026-05-11_21-42-08 merge_pr",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 sync_main_checkout",
+          "jskit session 2026-05-11_21-42-08 next",
+          "jskit session 2026-05-11_21-42-08 finish_session",
           "jskit session 2026-05-11_21-42-08 step --user-check failed --rework-notes -",
-          "jskit session 2026-05-11_21-42-08 rewind --step plan_made --json",
+          "jskit session 2026-05-11_21-42-08 rewind plan_made --json",
           "jskit session 2026-05-11_21-42-08 diff --json"
         ])
       })
     ]),
     fullUse:
-      "jskit session [create|<sessionId>] [step|diff|rewind|abandon|adopt-codex-thread] [--step <step_id>] [--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>] [--codex-result <text>|--codex-result-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>] [--prepare-merge true|--continue-to-merge true|--merge-pr true|--skip-merge|--skip-main-sync] [--user-check <passed|failed>] [--rework-notes <text>|--rework-notes-file <path>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
+      "jskit session [create|new|<sessionId>] [step|create_worktree|run_npm_install|define_issue|create_issue_file|create_issue_on_gh|make_plan|execute_plan|run_deep_ui_check|run_automated_checks|update_blueprint|commit_changes|create_pull_request_file|create_pr_on_gh|prepare_for_merge|merge_pr|sync_main_checkout|finish_session|next|skip|deslop|resolve-deslop|diff|rewind|abandon|adopt-codex-thread] [step_id] [--step <step_id>] [--prompt <text>] [--review-findings-remaining true|--review-findings-remaining false] [--resolve-deslop true] [--skip-step true|skip --skip-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"]),