@jskit-ai/jskit-cli 0.2.87 → 0.2.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.87",
+  "version": "0.2.89",
   "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.86",
-    "@jskit-ai/kernel": "0.1.78",
-    "@jskit-ai/shell-web": "0.1.77",
+    "@jskit-ai/jskit-catalog": "0.1.88",
+    "@jskit-ai/kernel": "0.1.80",
+    "@jskit-ai/shell-web": "0.1.79",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/sessionRuntime/constants.js

@@ -147,6 +147,10 @@ const JSKIT_STEP_RESULT_CONTRACT = Object.freeze({
   required: true,
   stepField: "step"
 });
+const MANUAL_JSKIT_STEP_RESULT_CONTRACT = Object.freeze({
+  ...JSKIT_STEP_RESULT_CONTRACT,
+  completionBehavior: "manual_advance"
+});
 const DESLOP_RESULT_CONTRACT = Object.freeze({
   autoResolvePriorities: Object.freeze(["high", "medium"]),
   completionBehavior: "deslop_loop",
@@ -231,7 +235,7 @@ function stepAutomationFor({
 const PLAN_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
   promptActionLabel: "Get Codex to execute plan",
-  responseContract: JSKIT_STEP_RESULT_CONTRACT
+  responseContract: MANUAL_JSKIT_STEP_RESULT_CONTRACT
 });
 const ISSUE_DETAILS_CODEX_HANDOFF = codexHandoff([
   ISSUE_CATEGORY_OUTPUT,
@@ -407,7 +411,7 @@ const STEP_DEFINITIONS = Object.freeze([
   defineStep({
     buttonLabel: "Get Codex to execute plan",
     codex: PLAN_EXECUTION_CODEX_HANDOFF,
-    description: "JSKIT sends the active cycle plan to Codex; Codex implements it; Studio advances when Codex finishes.",
+    description: "JSKIT sends the active cycle plan to Codex; Codex implements it; the user advances after reviewing completion.",
     id: "plan_executed",
     kind: "codex_prompt",
     label: "Plan executed",
@@ -473,28 +477,28 @@ const STEP_DEFINITIONS = Object.freeze([
       })
     ])
   }),
-  defineStep({
-    buttonLabel: "Commit accepted changes",
-    description: "JSKIT commits the user-accepted session changes in the session worktree.",
-    id: "changes_committed",
-    label: "Changes committed",
-    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "issue_url_exists", "github_auth", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed"]
-  }),
   defineStep({
     buttonLabel: "Update blueprint",
     codex: BLUEPRINT_CODEX_HANDOFF,
-    description: "JSKIT asks Codex to update durable app memory from the accepted work; Codex edits .jskit/APP_BLUEPRINT.md; JSKIT records and commits the update.",
+    description: "JSKIT asks Codex to update durable app memory from the accepted work; Codex edits .jskit/APP_BLUEPRINT.md; JSKIT records the update for the accepted-work commit.",
     id: "blueprint_updated",
     kind: "codex_prompt",
     label: "Blueprint updated",
-    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed"]
+  }),
+  defineStep({
+    buttonLabel: "Commit accepted changes",
+    description: "JSKIT commits the accepted session changes, including durable app memory updates, in the session worktree.",
+    id: "changes_committed",
+    label: "Changes committed",
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "issue_url_exists", "github_auth", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "blueprint_update_satisfied"]
   }),
   defineStep({
     buttonLabel: "Create final report",
     description: "JSKIT creates the deterministic final session report and comments it on the GitHub issue.",
     id: "final_report_created",
     label: "Final report created",
-    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed", "blueprint_update_satisfied"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "blueprint_update_satisfied", "accepted_changes_committed"]
   }),
   defineStep({
     buttonLabel: "Push branch and create PR",

package/src/server/sessionRuntime/preconditions.js

@@ -379,7 +379,7 @@ async function assertAcceptedChangesCommitted(paths) {
     ok: false,
     error: createError({
       code: "accepted_changes_not_committed",
-      message: "Accepted changes must be committed before app memory and finalization steps continue.",
+      message: "Accepted changes must be committed before finalization steps continue.",
       repairCommand: jskitCommand(`session ${paths.sessionId} step`)
     }),
     precondition: createPrecondition({

package/src/server/sessionRuntime/responses.js

@@ -56,6 +56,19 @@ function createPrecondition({
   });
 }
 
+function createWarning({
+  code,
+  message,
+  repairCommand = ""
+}) {
+  return createError({ code, message, repairCommand });
+}
+
+const ACCEPTED_CHANGES_NOOP_WARNING = createWarning({
+  code: "accepted_changes_noop",
+  message: "No accepted worktree changes were found; continuing without a new commit."
+});
+
 function normalizeStepId(stepId) {
   return normalizeText(stepId);
 }
@@ -530,6 +543,43 @@ function cloneContractValue(value) {
   );
 }
 
+function normalizeWarning(warning) {
+  if (typeof warning === "string") {
+    return createWarning({
+      code: "session_warning",
+      message: warning
+    });
+  }
+  if (!warning || typeof warning !== "object" || Array.isArray(warning)) {
+    return null;
+  }
+  return createWarning({
+    code: warning.code || "session_warning",
+    message: warning.message || "",
+    repairCommand: warning.repairCommand || ""
+  });
+}
+
+function mergeWarnings(...warningLists) {
+  const merged = [];
+  const seen = new Set();
+  for (const warnings of warningLists) {
+    for (const warning of Array.isArray(warnings) ? warnings : []) {
+      const normalized = normalizeWarning(warning);
+      if (!normalized?.message) {
+        continue;
+      }
+      const key = `${normalized.code}\n${normalized.message}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      merged.push(normalized);
+    }
+  }
+  return merged;
+}
+
 async function publicCodexContract(codex = null) {
   if (!codex || typeof codex !== "object" || Array.isArray(codex)) {
     return null;
@@ -731,7 +781,7 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
   })();
   const dynamicDescription = (() => {
     if (step.id === "plan_executed" && planExecutionPrompted && !planExecutionSubmitted) {
-      return "Codex has the execution prompt. Studio advances when Codex finishes.";
+      return "Codex has the execution prompt. Review the result, then use Go to next step when ready.";
     }
     if (step.id === "deep_ui_check_run" && deepUiCheckPrompted) {
       return "Codex has the Deep UI check prompt. Studio advances when Codex finishes.";
@@ -814,7 +864,8 @@ async function readSessionArtifacts(paths) {
     issueMetadataText,
     planExecutionReceipt,
     prOutcomeText,
-    mainCheckoutSyncText
+    mainCheckoutSyncText,
+    changesCommittedText
   ] = await Promise.all([
     readTrimmedFile(path.join(paths.sessionRoot, "status")),
     readTrimmedFile(path.join(paths.sessionRoot, "current_step")),
@@ -834,7 +885,8 @@ async function readSessionArtifacts(paths) {
     readTextIfExists(path.join(paths.sessionRoot, "issue_metadata.json")),
     readTextIfExists(path.join(cycleStepsRoot(paths, activeCycle), "plan_executed")),
     readTextIfExists(path.join(paths.sessionRoot, "pr_outcome.json")),
-    readTextIfExists(path.join(paths.sessionRoot, "main_checkout_sync.json"))
+    readTextIfExists(path.join(paths.sessionRoot, "main_checkout_sync.json")),
+    readTextIfExists(path.join(paths.sessionRoot, "changes_committed.json"))
   ]);
   let issueMetadata = null;
   if (issueMetadataText) {
@@ -871,6 +923,18 @@ async function readSessionArtifacts(paths) {
       mainCheckoutSync = null;
     }
   }
+  let acceptedChangesCommit = null;
+  if (changesCommittedText) {
+    try {
+      const parsed = JSON.parse(changesCommittedText);
+      acceptedChangesCommit = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    } catch {
+      acceptedChangesCommit = null;
+    }
+  }
+  const warnings = acceptedChangesCommit?.noChanges === true
+    ? [ACCEPTED_CHANGES_NOOP_WARNING]
+    : [];
   const cycles = await readCycles(paths, activeCycle);
   const checks = await readStructuredChecks(paths);
   const uiChecks = await readStructuredUiChecks(paths);
@@ -960,6 +1024,7 @@ async function readSessionArtifacts(paths) {
     finalReportText: finalReportText.trim(),
     prompt: prompt.trim(),
     status: status || SESSION_STATUS.PENDING,
+    warnings,
     workflowVersion,
     worktreeReady,
     worktreeStatus
@@ -980,7 +1045,8 @@ async function buildSessionResponse(paths, {
   errors = [],
   preconditions = [],
   prompt = undefined,
-  status = undefined
+  status = undefined,
+  warnings = []
 } = {}) {
   const responsePaths = paths.sessionId ? await pathsForExistingSession(paths) : paths;
   const artifacts = responsePaths.sessionRoot ? await readSessionArtifacts(responsePaths) : {};
@@ -1039,6 +1105,7 @@ async function buildSessionResponse(paths, {
           message: `Session ${paths.sessionId || ""} uses workflow version ${artifacts.workflowVersion || "missing"}, but this JSKIT runtime expects ${SESSION_WORKFLOW_VERSION}.`
         })
       ],
+      warnings: [],
       archive: responsePaths.archive || "active",
       sessionRoot: responsePaths.sessionRoot || "",
       worktree: paths.worktree || "",
@@ -1052,6 +1119,7 @@ async function buildSessionResponse(paths, {
   const responsePrompt = typeof prompt === "string"
     ? prompt
     : stepCanExposeStoredPrompt(currentStep) ? artifacts.prompt || "" : "";
+  const responseWarnings = mergeWarnings(artifacts.warnings || [], warnings);
 
   return {
     ok: ok === true,
@@ -1101,6 +1169,7 @@ async function buildSessionResponse(paths, {
     mainCheckoutSync: cloneContractValue(artifacts.mainCheckoutSync || null),
     preconditions,
     errors,
+    warnings: responseWarnings,
     archive: responsePaths.archive || (resolvedStatus === SESSION_STATUS.FINISHED ? "completed" : resolvedStatus === SESSION_STATUS.ABANDONED ? "abandoned" : "active"),
     sessionRoot: responsePaths.sessionRoot || "",
     worktree: paths.worktree || "",
@@ -1179,6 +1248,7 @@ function buildSessionErrorResponse({
     prOutcome: null,
     preconditions,
     errors: errorList,
+    warnings: [],
     archive: "",
     sessionRoot: "",
     worktree: "",

package/src/server/sessionRuntime.js

@@ -1,3 +1,6 @@
+import {
+  createHash
+} from "node:crypto";
 import {
   appendFile,
   mkdir,
@@ -1581,6 +1584,7 @@ const STEP_CANCELERS = Object.freeze({
   blueprint_updated: async (paths) => {
     await Promise.all([
       removePromptArtifact(paths, "update_blueprint.md"),
+      removeSessionRootFile(paths, BLUEPRINT_BASELINE_FILE),
       removeGlobalCodexResult(paths, "blueprint_updated")
     ]);
   },
@@ -1830,6 +1834,79 @@ async function changedFilesInWorktree(paths) {
   ]);
 }
 
+const BLUEPRINT_RELATIVE_PATH = ".jskit/APP_BLUEPRINT.md";
+const BLUEPRINT_BASELINE_FILE = "blueprint_update_baseline.json";
+
+function blueprintBaselinePath(paths) {
+  return path.join(paths.sessionRoot, BLUEPRINT_BASELINE_FILE);
+}
+
+function isBlueprintRelativePath(filePath = "") {
+  return normalizeText(filePath) === BLUEPRINT_RELATIVE_PATH;
+}
+
+function nonBlueprintChangedFiles(files = []) {
+  return files.filter((file) => !isBlueprintRelativePath(file));
+}
+
+async function hashWorktreeFile(paths, filePath) {
+  try {
+    const buffer = await readFile(path.join(paths.worktree, filePath));
+    return createHash("sha256").update(buffer).digest("hex");
+  } catch {
+    return "missing";
+  }
+}
+
+async function buildDirtyFileSnapshot(paths, files = []) {
+  const entries = await Promise.all(nonBlueprintChangedFiles(files).map(async (file) => [
+    file,
+    await hashWorktreeFile(paths, file)
+  ]));
+  return Object.fromEntries(entries);
+}
+
+async function writeBlueprintBaseline(paths) {
+  const changedFiles = await changedFilesInWorktree(paths);
+  const snapshot = await buildDirtyFileSnapshot(paths, changedFiles);
+  const payload = {
+    changedFiles: Object.keys(snapshot).sort((left, right) => left.localeCompare(right)),
+    files: snapshot,
+    recordedAt: timestampForReceipt()
+  };
+  await writeTextFile(blueprintBaselinePath(paths), `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+async function readBlueprintBaseline(paths) {
+  return parseJsonObject(await readTextIfExists(blueprintBaselinePath(paths))) || null;
+}
+
+async function unexpectedBlueprintStepChanges(paths, changedFiles = []) {
+  const baseline = await readBlueprintBaseline(paths);
+  if (!baseline?.files || typeof baseline.files !== "object" || Array.isArray(baseline.files)) {
+    return nonBlueprintChangedFiles(changedFiles);
+  }
+  const baselineFiles = baseline.files;
+  const currentFiles = new Set(nonBlueprintChangedFiles(changedFiles));
+  const candidates = new Set([
+    ...Object.keys(baselineFiles),
+    ...currentFiles
+  ]);
+  const unexpected = [];
+  for (const file of [...candidates].sort((left, right) => left.localeCompare(right))) {
+    if (!Object.prototype.hasOwnProperty.call(baselineFiles, file)) {
+      unexpected.push(file);
+      continue;
+    }
+    const currentHash = await hashWorktreeFile(paths, file);
+    if (currentHash !== baselineFiles[file]) {
+      unexpected.push(file);
+    }
+  }
+  return unexpected;
+}
+
 async function changedFilesSinceBase(paths) {
   const baseCommit = await readTrimmedFile(path.join(paths.sessionRoot, "base_commit"));
   const args = baseCommit
@@ -2178,17 +2255,10 @@ async function commitAcceptedChanges(paths, _options = {}, context = {}) {
 
   if (!commitInfo?.commit) {
     const result = await commitWorktree(paths, {
+      allowNoChanges: true,
       message: `Implement JSKIT session ${paths.sessionId}`
     });
     if (!result.ok) {
-      if (result.output === "No changes found.") {
-        return failSession(paths, {
-          code: "accepted_changes_missing",
-          message: "No accepted worktree changes found to commit.",
-          repairCommand: `git -C ${paths.worktree} status --short`,
-          preconditions
-        });
-      }
       return failSession(paths, {
         code: "accepted_changes_commit_failed",
         message: result.output || "Failed to commit accepted changes.",
@@ -2199,15 +2269,30 @@ async function commitAcceptedChanges(paths, _options = {}, context = {}) {
     commitInfo = {
       changedFiles: result.changedFiles || [],
       commit: await currentHead(paths),
-      committedAt: timestampForReceipt()
+      committedAt: timestampForReceipt(),
+      noChanges: (result.changedFiles || []).length < 1
     };
     await writeTextFile(path.join(paths.sessionRoot, "changes_committed.json"), `${JSON.stringify(commitInfo, null, 2)}\n`);
   }
 
-  await writeReceipt(paths, "changes_committed", `Committed accepted changes at ${commitInfo.commit || "unknown"}.`);
+  const warnings = [];
+  if (commitInfo.noChanges === true) {
+    warnings.push({
+      code: "accepted_changes_noop",
+      message: "No accepted worktree changes were found; continuing without a new commit."
+    });
+  }
+  await writeReceipt(
+    paths,
+    "changes_committed",
+    commitInfo.noChanges === true
+      ? "No accepted worktree changes were found; continued without a new commit."
+      : `Committed accepted changes at ${commitInfo.commit || "unknown"}.`
+  );
   await markStatus(paths, SESSION_STATUS.RUNNING);
   return buildSessionResponse(paths, {
-    preconditions
+    preconditions,
+    warnings
   });
 }
 
@@ -2220,7 +2305,7 @@ async function updateBlueprint(paths, options = {}, context = {}) {
   const { planPath } = await readCurrentPlan(paths);
   const issueDetailsPath = path.join(paths.sessionRoot, "issue_details.md");
   const agentDecisionsPath = path.join(paths.sessionRoot, "agent_decisions.md");
-  const blueprintPath = path.join(paths.worktree, ".jskit", "APP_BLUEPRINT.md");
+  const blueprintPath = path.join(paths.worktree, BLUEPRINT_RELATIVE_PATH);
   const blueprintPromptPath = path.join(paths.sessionRoot, "prompts", "update_blueprint.md");
 
   if (await fileExists(blueprintPromptPath)) {
@@ -2229,11 +2314,11 @@ async function updateBlueprint(paths, options = {}, context = {}) {
       return codexResultFailure;
     }
     const changedFiles = await changedFilesInWorktree(paths);
-    const unexpectedChanges = changedFiles.filter((file) => file !== ".jskit/APP_BLUEPRINT.md");
+    const unexpectedChanges = await unexpectedBlueprintStepChanges(paths, changedFiles);
     if (unexpectedChanges.length > 0) {
       return failSession(paths, {
         code: "blueprint_unexpected_changes",
-        message: `The blueprint step changed files outside .jskit/APP_BLUEPRINT.md: ${unexpectedChanges.join(", ")}`,
+        message: `The blueprint step changed files outside ${BLUEPRINT_RELATIVE_PATH}: ${unexpectedChanges.join(", ")}`,
         repairCommand: `git -C ${paths.worktree} status --short`,
         preconditions
       });
@@ -2249,30 +2334,8 @@ async function updateBlueprint(paths, options = {}, context = {}) {
       });
     }
 
-    if (changedFiles.includes(".jskit/APP_BLUEPRINT.md")) {
-      const addResult = await runGitInWorktree(paths.worktree, ["add", ".jskit/APP_BLUEPRINT.md"], {
-        timeout: 15000
-      });
-      if (!addResult.ok) {
-        return failSession(paths, {
-          code: "blueprint_stage_failed",
-          message: addResult.output || "Failed to stage app blueprint update.",
-          repairCommand: `git -C ${paths.worktree} add .jskit/APP_BLUEPRINT.md`,
-          preconditions
-        });
-      }
-      const commitResult = await runGitInWorktree(paths.worktree, ["commit", "-m", `Update app blueprint for ${paths.sessionId}`], {
-        timeout: 1000 * 60
-      });
-      if (!commitResult.ok) {
-        return failSession(paths, {
-          code: "blueprint_commit_failed",
-          message: commitResult.output || "Failed to commit app blueprint update.",
-          repairCommand: `git -C ${paths.worktree} status --short`,
-          preconditions
-        });
-      }
-      await writeReceipt(paths, "blueprint_updated", "Codex updated and JSKIT committed the app blueprint.");
+    if (changedFiles.includes(BLUEPRINT_RELATIVE_PATH)) {
+      await writeReceipt(paths, "blueprint_updated", "Codex updated the app blueprint; JSKIT will include it in the accepted changes commit.");
     } else {
       await writeReceipt(paths, "blueprint_updated", "Codex reviewed the app blueprint; no blueprint changes were needed.");
     }
@@ -2283,6 +2346,7 @@ async function updateBlueprint(paths, options = {}, context = {}) {
     });
   }
 
+  await writeBlueprintBaseline(paths);
   const prompt = await renderPrompt(paths, "update_blueprint.md", {
     agent_decisions_file: agentDecisionsPath,
     app_blueprint_file: blueprintPath,