@jskit-ai/jskit-cli 0.2.81 → 0.2.83

package/src/server/sessionRuntime/preconditions.js

@@ -6,6 +6,7 @@ import {
 import { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import {
+  JSKIT_CLI_SHELL_COMMAND,
   SESSION_STATE_RELATIVE_PATH
 } from "./constants.js";
 import {
@@ -24,6 +25,13 @@ import {
 import {
   hasWorktree
 } from "./worktrees.js";
+import {
+  inspectReadyJskitAppRoot
+} from "./appReadiness.js";
+
+function jskitCommand(args = "") {
+  return `${JSKIT_CLI_SHELL_COMMAND}${args ? ` ${args}` : ""}`;
+}
 
 async function assertTargetRootWritable(targetRoot) {
   try {
@@ -228,7 +236,7 @@ async function assertSessionExists(paths) {
     error: createError({
       code: "session_missing",
       message: `Session does not exist: ${paths.sessionId}`,
-      repairCommand: "jskit session create"
+      repairCommand: jskitCommand("session create")
     }),
     precondition: createPrecondition({
       id: "session_exists",
@@ -238,6 +246,255 @@ async function assertSessionExists(paths) {
   };
 }
 
+async function pathExists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function assertDependenciesInstalled(paths) {
+  if (await pathExists(path.join(paths.sessionRoot, "steps", "dependencies_installed"))) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "dependencies_installed",
+        ok: true,
+        message: "Session worktree dependencies have been installed."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "dependencies_not_installed",
+      message: "Cannot start issue work until dependencies are installed in the session worktree.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "dependencies_installed",
+      ok: false,
+      message: "Session worktree dependencies have been installed."
+    })
+  };
+}
+
+async function assertReadyJskitApp(paths) {
+  const root = paths.worktree || paths.targetRoot;
+  const readiness = await inspectReadyJskitAppRoot(root);
+  if (readiness.ok) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "ready_jskit_app",
+        ok: true,
+        message: "Session worktree has the required JSKIT app markers."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "app_setup_required",
+      message: `Issue sessions require a ready JSKIT app. Missing: ${readiness.missing.join(", ")}.`,
+      repairCommand: "Run the app setup flow before starting issue work."
+    }),
+    precondition: createPrecondition({
+      id: "ready_jskit_app",
+      ok: false,
+      message: "Session worktree has the required JSKIT app markers."
+    })
+  };
+}
+
+async function assertActiveCycleExists(paths) {
+  const activeCycle = await readTrimmedFile(path.join(paths.sessionRoot, "active_cycle"));
+  if (/^\d+$/u.test(activeCycle)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "active_cycle_exists",
+        ok: true,
+        message: "Active cycle marker exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "active_cycle_missing",
+      message: "Session active_cycle is missing or invalid."
+    }),
+    precondition: createPrecondition({
+      id: "active_cycle_exists",
+      ok: false,
+      message: "Active cycle marker exists."
+    })
+  };
+}
+
+async function assertActiveCycleUserCheckPassed(paths) {
+  const activeCycle = await readTrimmedFile(path.join(paths.sessionRoot, "active_cycle"));
+  const receiptPath = path.join(paths.sessionRoot, "steps", `cycle_${activeCycle}`, "user_check_completed");
+  if (await pathExists(receiptPath)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "active_cycle_user_check_passed",
+        ok: true,
+        message: "The active cycle user check has passed."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "user_check_not_passed",
+      message: "Finalization cannot continue until the active cycle user check has passed.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step --user-check passed`)
+    }),
+    precondition: createPrecondition({
+      id: "active_cycle_user_check_passed",
+      ok: false,
+      message: "The active cycle user check has passed."
+    })
+  };
+}
+
+async function assertAcceptedChangesCommitted(paths) {
+  const receiptPath = path.join(paths.sessionRoot, "steps", "changes_committed");
+  if (await pathExists(receiptPath)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "accepted_changes_committed",
+        ok: true,
+        message: "Accepted changes have been committed."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "accepted_changes_not_committed",
+      message: "Accepted changes must be committed before app memory and finalization steps continue.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "accepted_changes_committed",
+      ok: false,
+      message: "Accepted changes have been committed."
+    })
+  };
+}
+
+async function assertActiveCycleStepReceipt(paths, {
+  code,
+  id,
+  message,
+  stepId
+}) {
+  const activeCycle = await readTrimmedFile(path.join(paths.sessionRoot, "active_cycle"));
+  const receiptPath = path.join(paths.sessionRoot, "steps", `cycle_${activeCycle}`, stepId);
+  if (await pathExists(receiptPath)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id,
+        ok: true,
+        message
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code,
+      message,
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id,
+      ok: false,
+      message
+    })
+  };
+}
+
+async function assertAutomatedChecksPassed(paths) {
+  return assertActiveCycleStepReceipt(paths, {
+    code: "automated_checks_not_passed",
+    id: "automated_checks_passed",
+    message: "Automated checks have passed.",
+    stepId: "automated_checks_run"
+  });
+}
+
+async function assertDeepUiCheckSatisfied(paths) {
+  return assertActiveCycleStepReceipt(paths, {
+    code: "deep_ui_check_not_satisfied",
+    id: "deep_ui_check_satisfied",
+    message: "Deep UI check is satisfied.",
+    stepId: "deep_ui_check_run"
+  });
+}
+
+async function assertIssueMetadataExists(paths) {
+  const source = await readTextIfExists(path.join(paths.sessionRoot, "issue_metadata.json"));
+  if (!source) {
+    return {
+      ok: false,
+      error: createError({
+        code: "issue_metadata_missing",
+        message: "Cannot continue before issue_metadata.json records the issue category and UI impact.",
+        repairCommand: jskitCommand(`session ${paths.sessionId} step --issue-details -`)
+      }),
+      precondition: createPrecondition({
+        id: "issue_metadata_exists",
+        ok: false,
+        message: "Issue metadata records issue category and UI impact."
+      })
+    };
+  }
+
+  let metadata = null;
+  try {
+    metadata = JSON.parse(source);
+  } catch {
+    metadata = null;
+  }
+  const issueCategory = String(metadata?.issueCategory || "").trim().toLowerCase();
+  const uiImpact = String(metadata?.uiImpact || "").trim().toLowerCase();
+  const validIssueCategories = new Set(["client", "server", "client_server", "tooling", "unknown"]);
+  const validUiImpacts = new Set(["none", "possible", "definite", "unknown"]);
+  if (validIssueCategories.has(issueCategory) && validUiImpacts.has(uiImpact)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "issue_metadata_exists",
+        ok: true,
+        message: "Issue metadata records issue category and UI impact."
+      })
+    };
+  }
+
+  return {
+    ok: false,
+    error: createError({
+      code: "issue_metadata_invalid",
+      message: "issue_metadata.json must include a valid issueCategory and uiImpact.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step --issue-details -`)
+    }),
+    precondition: createPrecondition({
+      id: "issue_metadata_exists",
+      ok: false,
+      message: "Issue metadata records issue category and UI impact."
+    })
+  };
+}
+
 async function assertIssueTextExists(paths) {
   const issueText = await readTrimmedFile(path.join(paths.sessionRoot, "issue.md"));
   if (issueText) {
@@ -255,7 +512,7 @@ async function assertIssueTextExists(paths) {
     error: createError({
       code: "issue_text_missing",
       message: "Cannot create a GitHub issue before issue.md exists.",
-      repairCommand: `jskit session ${paths.sessionId} step --issue -`
+      repairCommand: jskitCommand(`session ${paths.sessionId} step --issue -`)
     }),
     precondition: createPrecondition({
       id: "issue_text_exists",
@@ -282,7 +539,7 @@ async function assertIssueUrlExists(paths) {
     error: createError({
       code: "issue_url_missing",
       message: "Cannot create a plan before the GitHub issue exists.",
-      repairCommand: `jskit session ${paths.sessionId} step`
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
     }),
     precondition: createPrecondition({
       id: "issue_url_exists",
@@ -292,6 +549,114 @@ async function assertIssueUrlExists(paths) {
   };
 }
 
+async function assertPlanTextExists(paths) {
+  const activeCycle = await readTrimmedFile(path.join(paths.sessionRoot, "active_cycle"));
+  const planPath = path.join(paths.sessionRoot, "cycles", `cycle_${activeCycle || "001"}`, "plan.md");
+  const planText = await readTrimmedFile(planPath);
+  if (planText) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "plan_text_exists",
+        ok: true,
+        message: "Plan text exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "plan_text_missing",
+      message: "Cannot execute a plan before the active cycle plan exists.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step --plan -`)
+    }),
+    precondition: createPrecondition({
+      id: "plan_text_exists",
+      ok: false,
+      message: "Plan text exists."
+    })
+  };
+}
+
+async function assertIssueDetailsExists(paths) {
+  const issueDetails = await readTrimmedFile(path.join(paths.sessionRoot, "issue_details.md"));
+  if (issueDetails) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "issue_details_exists",
+        ok: true,
+        message: "Issue details exist."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "issue_details_missing",
+      message: "Cannot create a plan before issue_details.md exists.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step --issue-details -`)
+    }),
+    precondition: createPrecondition({
+      id: "issue_details_exists",
+      ok: false,
+      message: "Issue details exist."
+    })
+  };
+}
+
+async function assertBlueprintUpdateSatisfied(paths) {
+  if (await pathExists(path.join(paths.sessionRoot, "steps", "blueprint_updated"))) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "blueprint_update_satisfied",
+        ok: true,
+        message: "Blueprint update step is complete."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "blueprint_update_missing",
+      message: "Cannot continue before the blueprint update step is complete.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "blueprint_update_satisfied",
+      ok: false,
+      message: "Blueprint update step is complete."
+    })
+  };
+}
+
+async function assertFinalReportExists(paths) {
+  if (await pathExists(path.join(paths.sessionRoot, "final_report.md"))) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "final_report_exists",
+        ok: true,
+        message: "Final report exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "final_report_missing",
+      message: "Cannot publish the PR before final_report.md exists.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "final_report_exists",
+      ok: false,
+      message: "Final report exists."
+    })
+  };
+}
+
 async function assertWorktreeExists(paths) {
   if (await hasWorktree(paths)) {
     return {
@@ -308,7 +673,7 @@ async function assertWorktreeExists(paths) {
     error: createError({
       code: "worktree_missing",
       message: "Session worktree does not exist.",
-      repairCommand: `jskit session ${paths.sessionId} step`
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
     }),
     precondition: createPrecondition({
       id: "worktree_exists",
@@ -335,7 +700,7 @@ async function assertPrUrlExists(paths) {
     error: createError({
       code: "pr_url_missing",
       message: "Cannot merge before pr_url exists.",
-      repairCommand: `jskit session ${paths.sessionId} step`
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
     }),
     precondition: createPrecondition({
       id: "pr_url_exists",
@@ -347,13 +712,25 @@ async function assertPrUrlExists(paths) {
 
 export {
   applyPreconditions,
+  assertAcceptedChangesCommitted,
+  assertActiveCycleExists,
+  assertActiveCycleUserCheckPassed,
+  assertBlueprintUpdateSatisfied,
+  assertDeepUiCheckSatisfied,
+  assertDependenciesInstalled,
+  assertFinalReportExists,
   assertGhAuth,
   assertGitCurrentBranch,
   assertGitRepository,
   assertGithubOrigin,
+  assertIssueMetadataExists,
   assertIssueTextExists,
   assertIssueUrlExists,
+  assertAutomatedChecksPassed,
+  assertIssueDetailsExists,
+  assertPlanTextExists,
   assertPrUrlExists,
+  assertReadyJskitApp,
   assertSessionExists,
   assertTargetRootWritable,
   assertWorktreeExists,

package/src/server/sessionRuntime/promptRenderer.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import {
+  JSKIT_CLI_SHELL_RULE,
   PROMPT_DIRECTORY,
   SESSION_STATE_RELATIVE_PATH
 } from "./constants.js";
@@ -24,9 +25,20 @@ function renderTemplate(source, values = {}) {
   });
 }
 
+function withShellCommandRule(template) {
+  const body = String(template || "").trim();
+  if (!body) {
+    return JSKIT_CLI_SHELL_RULE;
+  }
+  if (body.includes("When running JSKIT CLI commands from the shell")) {
+    return body;
+  }
+  return `${JSKIT_CLI_SHELL_RULE}\n\n---\n\n${body}`;
+}
+
 async function renderPrompt(paths, templateName, values = {}) {
   const template = await readPromptTemplate(paths.targetRoot, templateName);
-  return renderTemplate(template, {
+  return renderTemplate(withShellCommandRule(template), {
     branch: paths.branch,
     session_id: paths.sessionId,
     worktree: paths.worktree,
@@ -37,5 +49,6 @@ async function renderPrompt(paths, templateName, values = {}) {
 export {
   readPromptTemplate,
   renderPrompt,
-  renderTemplate
+  renderTemplate,
+  withShellCommandRule
 };

package/src/server/sessionRuntime/prompts/automated_checks.md

@@ -0,0 +1,42 @@
+Run automated checks for JSKIT session {{session_id}}.
+
+Worktree:
+
+{{worktree}}
+
+Command:
+
+{{check_command}}
+
+Run the command in the session worktree. If it fails, diagnose the root cause, fix the worktree, and rerun the command. Keep repeating until the command passes or until a real blocker prevents progress.
+
+Rules:
+
+- Fix the underlying cause. Do not remove checks, weaken verification, or hide failures to make the command pass.
+- Prefer JSKIT-owned helpers, generators, package seams, and documented commands over local hacks.
+- Use `npx --no-install jskit ...` for JSKIT CLI commands you run directly from the shell.
+- Keep fixes scoped to the current issue, issue details, and active plan.
+- Do not create commits, branches, issues, pull requests, merges, or worktree cleanup. JSKIT session owns those steps.
+
+When finished, report:
+
+- root cause
+- files changed
+- final check command and result
+- anything still unverified
+
+If the repair records a meaningful verification decision, tradeoff, missing coverage, or root-cause explanation future steps should know, include concise entries with reasons in this exact marker block:
+
+```text
+[agent_decisions]
+<verification or repair decisions, or "No new decisions.">
+[/agent_decisions]
+```
+
+At the very end, include this completion block so Studio knows the step is complete:
+
+[jskit_step_result]
+status: complete
+step: automated_checks_run
+summary: Short summary of the final check command, result, and any repairs.
+[/jskit_step_result]

package/src/server/sessionRuntime/prompts/deep_ui_check.md

@@ -0,0 +1,53 @@
+Deep UI quality check for JSKIT session {{session_id}}.
+
+Phase: {{phase}}
+GitHub issue: {{issue_url}}
+Issue number: {{issue_number}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Issue details file (`issue_details.md`): {{issue_details_file}}
+Plan file: {{plan_file}}
+UI impact: {{ui_impact}}
+Worktree: {{worktree}}
+
+Changed files since the session base:
+
+{{changed_files}}
+
+Run a focused UI quality pass for the current worktree. If this is not UI-impacting after inspection, say exactly why and do not edit files. If the issue touches UI, inspect the changed routes, views, components, placements, layouts, and styles.
+
+Check:
+
+- Material Design quality.
+- Vuetify best practices.
+- visual hierarchy and density.
+- spacing and alignment.
+- responsive behavior on mobile, tablet, and desktop.
+- loading, empty, error, disabled, and success states where relevant.
+- accessibility basics.
+- route and navigation coherence.
+- consistency with the existing app style.
+
+When clear scoped UI issues exist, fix them in the worktree. Keep fixes limited to the issue, confirmed issue details, and approved plan.
+
+Use Playwright for a meaningful route check when possible. If login is required, use a development-only auth bootstrap path. When possible, record UI verification with:
+
+`npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`
+
+Do not create commits, branches, issues, pull requests, merges, or worktree cleanup. JSKIT session owns those steps.
+
+If this pass makes UI fixes, intentionally skips UI work after inspection, changes a design direction, or leaves a meaningful UI verification gap, include concise decision entries with reasons in this exact marker block:
+
+```text
+[agent_decisions]
+<Deep UI decisions or "No new decisions.">
+[/agent_decisions]
+```
+
+At the very end, include this completion block so Studio knows the step is complete:
+
+[jskit_step_result]
+status: complete
+step: deep_ui_check_run
+summary: Short summary of UI findings, fixes, verification, or why no UI work applied.
+[/jskit_step_result]

package/src/server/sessionRuntime/prompts/execute_plan.md

@@ -4,24 +4,35 @@ GitHub issue: {{issue_url}}
 Issue number: {{issue_number}}
 Issue title: {{issue_title}}
 Issue body file: {{issue_file}}
+Issue details file (`issue_details.md`): {{issue_details_file}}
 Plan file: {{plan_file}}
 Worktree: {{worktree}}
 
-Implement the plan in the session worktree. Keep the change scoped to the issue and approved plan.
+Confirmed issue details:
+
+{{issue_details_text}}
+
+Approved plan:
+
+{{plan_text}}
+
+Implement the plan in the session worktree. Keep the change scoped to the issue, confirmed issue details, and approved plan.
 
 Implementation rules:
 
-- Inspect the current app before editing. Do not assume a JSKIT app shape without checking files.
-- Prefer existing JSKIT helpers, package runtime seams, generated scaffolds, and documented generators over new local helpers.
-- If the plan calls for a generator or package install, use the planned `jskit` command unless inspection proves it does not apply. If you skip a generator, explain the exact gap.
-- For non-CRUD route pages, use `jskit generate ui-generator page ...` when it fits instead of hand-writing both route files and placement entries.
+- Inspect the current app before editing. App setup has already passed; if required JSKIT app files are missing, report setup failure rather than inventing recovery work.
+- Follow both `{{issue_details_file}}` and `{{plan_file}}`. If they disagree, ask for clarification before changing files.
+- Read `.jskit/helper-map.md` when it exists before creating helpers, composables, service functions, maps, or package glue.
+- Prefer existing JSKIT helpers, app-local helpers, package runtime seams, generated scaffolds, and documented generators over new local helpers.
+- If the plan calls for a generator or package install, use the planned `npx --no-install jskit` command unless inspection proves it does not apply. If you skip a generator, explain the exact gap.
+- For non-CRUD route pages, use `npx --no-install jskit generate ui-generator page ...` when it fits instead of hand-writing both route files and placement entries.
 - For CRUD work, scaffold the server side first with `crud-server-generator` before CRUD UI or CRUD route work.
 - Do not hand-write a separate CRUD migration for a table owned by `crud-server-generator`.
 - Do not hand-build CRUD endpoints or page trees before the server CRUD package and shared resource file exist.
 - Keep direct knex exceptional and minimal. Prefer internal json-rest-api seams outside generated CRUD packages and explicit weird-custom feature lanes.
 - Keep runtime, UI, and data concerns separated.
 - Avoid accidental scope expansion.
-- Do not create old workflow files such as `.jskit/WORKBOARD.md`; the session files and receipts are the workflow record.
+- Do not create `.jskit/WORKBOARD.md`; the session files and receipts are the workflow record.
 - If user-facing UI changes, bring the screen to Material Design and Vuetify quality before calling it done. Include coherent responsive layout, loading, empty, error, disabled, and success states where relevant.
 - If verification needs login, use the app's local development auth bootstrap path rather than a live external auth login.
 
@@ -29,7 +40,22 @@ After making changes:
 
 - Review for repeated code, unnecessary helpers, fragmented functions, placeholder work, missing states, broken route wiring, ownership mistakes, and weak JSKIT reuse.
 - Run the smallest relevant checks you can run safely in the worktree.
-- For changed user-facing UI, run or clearly identify the Playwright verification path. When possible, record UI verification with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
+- For changed user-facing UI, run or clearly identify the Playwright verification path. When possible, record UI verification with `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
 - Summarize changed files and checks run.
+- If implementation deviated from the approved plan, generator choices, package ownership, helper reuse, UI verification path, or data ownership, include concise decision entries with reasons in this exact marker block:
+
+```text
+[agent_decisions]
+<implementation decisions or "No new decisions.">
+[/agent_decisions]
+```
 
 Do not create commits, branches, issues, pull requests, merges, or worktree cleanup yourself. JSKIT session will handle those steps.
+
+At the very end, include this completion block so Studio knows the step is complete:
+
+[jskit_step_result]
+status: complete
+step: plan_executed
+summary: Short summary of what changed and what was checked.
+[/jskit_step_result]

package/src/server/sessionRuntime/prompts/final_comment.md

@@ -1,8 +1,10 @@
 Codex thread id: {{codex_thread_id}}
 Issue session status: finished
 PR: {{pr_url}}
+PR outcome: {{pr_outcome}}
+Outcome reason: {{pr_outcome_reason}}
 Local transcript: {{transcript_log}}
 
 Summary:
 
-Session {{session_id}} finished and merged.
+Session {{session_id}} finished with PR outcome `{{pr_outcome}}`.