@jskit-ai/jskit-cli 0.2.80 → 0.2.82

package/src/server/sessionRuntime/preconditions.js

@@ -1,12 +1,12 @@
 import {
   access,
   appendFile,
-  mkdir,
-  stat
+  mkdir
 } from "node:fs/promises";
 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 {
@@ -22,6 +22,16 @@ import {
 import {
   resolveExistingSessionRoot
 } from "./paths.js";
+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 {
@@ -226,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",
@@ -236,32 +246,251 @@ async function assertSessionExists(paths) {
   };
 }
 
-async function assertIssueArtifacts(paths) {
-  const [issueText, issueUrl] = await Promise.all([
-    readTrimmedFile(path.join(paths.sessionRoot, "issue.md")),
-    readTrimmedFile(path.join(paths.sessionRoot, "issue_url"))
-  ]);
-  if (issueText && issueUrl) {
+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: "issue_artifacts",
+        id: "accepted_changes_committed",
         ok: true,
-        message: "Issue text and GitHub issue URL exist."
+        message: "Accepted changes have been committed."
       })
     };
   }
   return {
     ok: false,
     error: createError({
-      code: "issue_artifacts_missing",
-      message: "Issue text and GitHub issue URL are required.",
-      repairCommand: `jskit session ${paths.sessionId} step`
+      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: "issue_artifacts",
+      id: "accepted_changes_committed",
       ok: false,
-      message: "Issue text and GitHub issue URL exist."
+      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."
     })
   };
 }
@@ -283,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",
@@ -293,13 +522,139 @@ async function assertIssueTextExists(paths) {
   };
 }
 
-async function hasWorktree(paths) {
-  try {
-    const stats = await stat(paths.worktree);
-    return stats.isDirectory();
-  } catch {
-    return false;
+async function assertIssueUrlExists(paths) {
+  const issueUrl = await readTrimmedFile(path.join(paths.sessionRoot, "issue_url"));
+  if (issueUrl) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "issue_url_exists",
+        ok: true,
+        message: "GitHub issue URL exists."
+      })
+    };
   }
+  return {
+    ok: false,
+    error: createError({
+      code: "issue_url_missing",
+      message: "Cannot create a plan before the GitHub issue exists.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "issue_url_exists",
+      ok: false,
+      message: "GitHub issue URL exists."
+    })
+  };
+}
+
+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) {
@@ -318,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",
@@ -345,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",
@@ -357,13 +712,25 @@ async function assertPrUrlExists(paths) {
 
 export {
   applyPreconditions,
+  assertAcceptedChangesCommitted,
+  assertActiveCycleExists,
+  assertActiveCycleUserCheckPassed,
+  assertBlueprintUpdateSatisfied,
+  assertDeepUiCheckSatisfied,
+  assertDependenciesInstalled,
+  assertFinalReportExists,
   assertGhAuth,
   assertGitCurrentBranch,
   assertGitRepository,
   assertGithubOrigin,
-  assertIssueArtifacts,
+  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/app_blueprint.md

@@ -4,21 +4,45 @@ App brief:
 
 {{app_brief}}
 
-Produce a concise but useful app-level blueprint. It must describe product intent, not implementation steps for the current issue.
+Produce a concise but useful app-level blueprint. It must describe product intent, platform choices, and architectural boundaries. It must not become an implementation workboard for one issue.
+
+Before writing the blueprint, classify the app state if local files are available:
+
+- empty
+- non_jskit_repo
+- partial_jskit_app
+- jskit_app
+
+Use these markers for a real JSKIT app when they exist:
+
+- package.json
+- config/public.js
+- src/main.js
+- packages/main/package.descriptor.mjs
+- .jskit/lock.json
+
+If the app is empty or only a fresh minimal scaffold, keep platform choices explicit and provisional until decided. Do not treat a missing `config.tenancyMode` line or untouched minimal scaffold as a final tenancy decision.
 
 Cover:
 
 - App purpose and what the app will do in general.
 - Primary users and actors.
 - Type of multihoming or tenancy: none, personal, workspaces, or another explicit model from the brief.
+- Database engine, if the app needs persistence.
+- Auth provider, if the app needs auth.
 - The role of each surface: app, admin, console, settings, public, workspace, or any app-specific surface from the brief.
 - Global view of the main product areas and navigation destinations.
 - Key domain concepts and data objects, without inventing database schemas unless the brief clearly requires them.
+- Ownership model per persistent entity when it is already clear: public, user, workspace, or workspace_user.
+- Baseline JSKIT package workflows to accept as defaults and any intended overrides.
+- Package install, generator, and custom-code areas at a high level.
+- CRUDs likely to need server ownership, and any narrow exceptions that should be called out later.
 - Important non-goals and constraints.
 - First useful screen and what it should show.
 - Settings, admin, and operator expectations when relevant.
+- Verification expectations, including UI checks for user-facing screens.
 
-If the brief is ambiguous, state the assumption in the blueprint instead of asking questions.
+If the brief is ambiguous, state the assumption in the blueprint instead of asking questions. Do not invent detailed feature behavior that the brief does not support.
 
 When the blueprint is ready, output only the final markdown surrounded by these exact markers:
 

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]