@jskit-ai/jskit-cli 0.2.80 → 0.2.81

package/src/server/sessionRuntime/preconditions.js

@@ -1,8 +1,7 @@
 import {
   access,
   appendFile,
-  mkdir,
-  stat
+  mkdir
 } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
 import path from "node:path";
@@ -22,6 +21,9 @@ import {
 import {
   resolveExistingSessionRoot
 } from "./paths.js";
+import {
+  hasWorktree
+} from "./worktrees.js";
 
 async function assertTargetRootWritable(targetRoot) {
   try {
@@ -236,72 +238,60 @@ 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 assertIssueTextExists(paths) {
+  const issueText = await readTrimmedFile(path.join(paths.sessionRoot, "issue.md"));
+  if (issueText) {
     return {
       ok: true,
       precondition: createPrecondition({
-        id: "issue_artifacts",
+        id: "issue_text_exists",
         ok: true,
-        message: "Issue text and GitHub issue URL exist."
+        message: "Issue text exists."
       })
     };
   }
   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: "issue_text_missing",
+      message: "Cannot create a GitHub issue before issue.md exists.",
+      repairCommand: `jskit session ${paths.sessionId} step --issue -`
     }),
     precondition: createPrecondition({
-      id: "issue_artifacts",
+      id: "issue_text_exists",
       ok: false,
-      message: "Issue text and GitHub issue URL exist."
+      message: "Issue text exists."
     })
   };
 }
 
-async function assertIssueTextExists(paths) {
-  const issueText = await readTrimmedFile(path.join(paths.sessionRoot, "issue.md"));
-  if (issueText) {
+async function assertIssueUrlExists(paths) {
+  const issueUrl = await readTrimmedFile(path.join(paths.sessionRoot, "issue_url"));
+  if (issueUrl) {
     return {
       ok: true,
       precondition: createPrecondition({
-        id: "issue_text_exists",
+        id: "issue_url_exists",
         ok: true,
-        message: "Issue text exists."
+        message: "GitHub issue URL exists."
       })
     };
   }
   return {
     ok: false,
     error: createError({
-      code: "issue_text_missing",
-      message: "Cannot create a GitHub issue before issue.md exists.",
-      repairCommand: `jskit session ${paths.sessionId} step --issue -`
+      code: "issue_url_missing",
+      message: "Cannot create a plan before the GitHub issue exists.",
+      repairCommand: `jskit session ${paths.sessionId} step`
     }),
     precondition: createPrecondition({
-      id: "issue_text_exists",
+      id: "issue_url_exists",
       ok: false,
-      message: "Issue text exists."
+      message: "GitHub issue URL exists."
     })
   };
 }
 
-async function hasWorktree(paths) {
-  try {
-    const stats = await stat(paths.worktree);
-    return stats.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
 async function assertWorktreeExists(paths) {
   if (await hasWorktree(paths)) {
     return {
@@ -361,8 +351,8 @@ export {
   assertGitCurrentBranch,
   assertGitRepository,
   assertGithubOrigin,
-  assertIssueArtifacts,
   assertIssueTextExists,
+  assertIssueUrlExists,
   assertPrUrlExists,
   assertSessionExists,
   assertTargetRootWritable,

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/doctor_failure.md

@@ -12,4 +12,15 @@ Failure output:
 
 {{doctor_output}}
 
-Fix the root cause in this worktree. Do not push, open a PR, merge, or remove the worktree. When the fix is ready, report changed files and verification, then the user will rerun the JSKIT session step.
+Fix the root cause in this worktree. Do not silence the failure or remove checks to make the step pass.
+
+Diagnosis rules:
+
+- Identify whether the failure is dependency/setup, JSKIT metadata, generated contract drift, routing/surface wiring, CRUD ownership, UI verification receipt, test-auth, or ordinary application code.
+- Prefer repairing the JSKIT-owned contract or generated metadata over adding local-path hacks.
+- Do not run `npm install` only because optional agent docs are missing. Run installs only when the failure or a JSKIT setup/session step requires dependency repair.
+- If a generator/package command is the correct repair, use the `jskit` command rather than hand-recreating generated structure.
+- For UI receipt failures, run the relevant Playwright check and record it with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` when possible.
+- If login is required, use the app's development auth bootstrap path rather than a live external auth flow.
+
+Do not push, open a PR, merge, or remove the worktree. When the fix is ready, report the root cause, files changed, verification, and anything still unverified. The user or Studio will rerun the JSKIT session step.

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

@@ -0,0 +1,35 @@
+Execute the approved implementation plan for JSKIT session {{session_id}}.
+
+GitHub issue: {{issue_url}}
+Issue number: {{issue_number}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Plan file: {{plan_file}}
+Worktree: {{worktree}}
+
+Implement the plan in the session worktree. Keep the change scoped to the issue 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.
+- 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.
+- 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.
+
+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>`.
+- Summarize changed files and checks run.
+
+Do not create commits, branches, issues, pull requests, merges, or worktree cleanup yourself. JSKIT session will handle those steps.

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

@@ -2,12 +2,30 @@ Create a GitHub issue from this user request:
 
 {{user_input}}
 
-Ask clarifying questions if the request is not specific enough to produce a useful implementation issue.
+First inspect the local app enough to understand the request in context. Use package.json, config, .jskit metadata, routes, packages, and any saved app blueprint when available. Classify the current app state as empty, non_jskit_repo, partial_jskit_app, or jskit_app before assuming ordinary feature work is possible.
 
-When the issue text is ready, output only the final issue body surrounded by these exact markers:
+Draft an implementation-ready issue, not a broad product essay.
+
+Preserve these JSKIT boundaries:
+
+- If the app is empty or a partial JSKIT app, the issue should be about bootstrap or recovery before feature implementation.
+- If platform choices are still provisional, make the issue resolve those choices before installing tenancy-sensitive packages.
+- Do not ask the developer to redesign standard JSKIT package-owned workflows from scratch. Treat selected package workflows as defaults unless the request asks for overrides, restrictions, or custom additions.
+- For persisted app-owned data, prefer generated/package ownership over direct hand-built persistence. A new ordinary table should usually become a server CRUD-owned entity before CRUD UI or route work.
+- For non-CRUD app pages, prefer the JSKIT UI generator when it fits.
+- Keep direct knex or low-level runtime work exceptional and explicitly justified.
+- Do not include workflow bookkeeping such as old workboards in the issue body. JSKIT session state and receipts are the workflow tracker.
+
+Ask concise clarifying questions if the request is not specific enough to produce a useful implementation issue. Ask only for details that materially change the ticket.
+
+When the issue is ready, output only the final issue title and body surrounded by these exact markers:
+
+[issue_title]
+<short issue title>
+[/issue_title]
 
 [issue_text]
-<issue title and body>
+<issue body in Markdown, without repeating the title as a heading>
 [/issue_text]
 
 The issue should be concrete, scoped, and implementation-ready. Include acceptance criteria when they are useful.

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

@@ -0,0 +1,50 @@
+Create an implementation plan for JSKIT session {{session_id}}.
+
+GitHub issue: {{issue_url}}
+Issue number: {{issue_number}}
+Issue title: {{issue_title}}
+Issue body file: {{issue_file}}
+Issue title file: {{issue_title_file}}
+Plan file to create: {{plan_file}}
+Worktree: {{worktree}}
+
+Read the issue and inspect the local app before planning. Use the issue files, package.json, .jskit metadata, config, packages, routes, generated references, package docs, and any saved app blueprint when available.
+
+Start by identifying the app state and the implementation lane:
+
+- empty, non_jskit_repo, partial_jskit_app, or jskit_app
+- package install
+- generator scaffolding
+- custom local code
+- a combination of those
+
+Planning rules:
+
+- Keep the plan scoped to the issue. Avoid "while I am here" work.
+- Prefer vertical slices that produce visible or end-to-end progress.
+- If the work is too broad to review confidently, split it into clear chunks.
+- Make generator decisions concrete. Name the exact `jskit` commands to run when a generator or package install applies.
+- For non-CRUD route page work, plan to check `jskit show ui-generator --details` and `jskit list-placements` before hand-writing pages or placement entries.
+- For CRUD work, plan server ownership first. Name the `jskit generate crud-server-generator scaffold ...` command before any CRUD UI plan.
+- For CRUD-owned tables, plan around the real database table shape. Do not plan a separate hand-written migration for a table that `crud-server-generator` will own.
+- Every persisted app-owned table should have generated/package CRUD ownership unless there is a narrow explicit exception.
+- Do not hand-build CRUD routes, CRUD endpoints, or CRUD page trees before the server CRUD package and shared resource file exist.
+- `feature-server-generator` is for non-CRUD workflows and orchestration, not ordinary persisted entity tables.
+- Keep runtime, UI, and data concerns separated.
+- Keep direct knex exceptional and minimal. Prefer internal json-rest-api seams outside generated CRUD packages and explicit weird-custom feature lanes.
+- For package-owned baseline workflows, plan to install and verify the baseline before inventing custom code around it.
+- For user-facing UI, include Material/Vuetify quality expectations and a Playwright verification path.
+- If login is required for UI verification, plan for a development-only auth bootstrap path instead of live external auth.
+- Do not create or update the old `.jskit/WORKBOARD.md` workflow. JSKIT session state, receipts, issue text, plan file, transcript, and commits are the tracker.
+
+If setup values are needed, ask plainly using exact env var or option names. For example: DB_NAME, DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, AUTH_SUPABASE_URL, AUTH_SUPABASE_PUBLISHABLE_KEY, APP_PUBLIC_URL.
+
+If the issue is not clear enough to plan safely, ask the user concise follow-up questions first.
+
+When the plan is ready, output only the final plan surrounded by these exact markers:
+
+[plan]
+<implementation plan in Markdown>
+[/plan]
+
+Keep the plan concrete and implementation-oriented. Include the likely files or areas to touch, ordered steps, generator commands to consider, review expectations, and checks that should be run.

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

@@ -12,4 +12,17 @@ Failure output:
 
 {{doctor_output}}
 
-Diagnose the failure and fix only what is required in this worktree. Do not push, open a PR, merge, or remove the worktree unless JSKIT Studio explicitly instructs it.
+Diagnose the failure and fix only what is required in this worktree.
+
+Check for:
+
+- missing or wrong GitHub remote
+- missing GitHub auth
+- branch push failure
+- PR body/title issue
+- stale local git state
+- rejected merge or failing required checks
+
+Use repository-portable repairs only. Do not hard-code local paths or credentials. Do not create a parallel manual workflow around the JSKIT session.
+
+Do not push, open a PR, merge, or remove the worktree unless JSKIT Studio or the JSKIT session step explicitly instructs it. Report root cause, changed files, commands run, and remaining risk.

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

@@ -1,22 +1,43 @@
-Review pass {{review_pass}} for session {{session_id}}.
-
-{{review_pass_note}}
+Review changes for session {{session_id}}.
 
 Changed files from the latest commit:
 
 {{changed_files}}
 
-Check through the changed code and see if the changes are done without problems:
+Review the committed changes and fix important issues in this worktree when the fix is clear and scoped.
+
+Use four passes:
+
+1. Deslop review
+   - repeated functions or duplicated local helpers
+   - helpers reimplemented locally when a kernel/runtime seam already exists
+   - placeholder, fake-complete, or vague UI/copy/code structure
+   - dead code, unused props/imports, TODO-shaped gaps, or accidental abstractions
+   - missing loading, empty, error, permission, or ownership states
+   - broken flows, missing route wiring, missing migrations, or stale generated metadata
+   - surface or entity ownership mistakes: public, user, workspace, workspace_user
+2. JSKIT review
+   - existing helper/runtime seam available?
+   - should this have been a package install, generator step, or scaffold extension instead of hand code?
+   - if a generator existed, was the exact `jskit` command used or was the gap documented?
+   - for CRUD work, was `crud-server-generator scaffold` used before CRUD UI or CRUD route hand-coding?
+   - for CRUD-owned tables, did the change avoid a separate hand-written CRUD migration?
+   - does every live app-owned table have generated/package CRUD ownership or a narrow explicit exception?
+   - is direct app-owned knex usage limited to generated CRUD packages or explicit weird-custom feature lanes?
+   - are surface, route, ownership, package metadata, and migration choices aligned with JSKIT conventions?
+3. UI standards review
+   - user-facing screens follow Material Design and Vuetify best practices
+   - list screens have clear hierarchy, actions, density, empty states, and table/list patterns
+   - view and edit/new screens have clear grouping, labels, helper text, validation, spacing, and action placement
+   - responsive layout, loading, disabled, success, and error states are coherent
+   - improve weak screens before sign-off when the fix is scoped
+4. Verification review
+   - run the smallest relevant verification commands for the changed scope
+   - any changed user-facing UI should be exercised with Playwright when possible
+   - UI verification should normally be recorded through `jskit app verify-ui`
+   - if login is required, use the chosen local test-auth path instead of live external auth
+   - if there is no usable local auth bootstrap path, record it as a blocking testability gap
 
-- slop
-- repeated code
-- ownership issues
-- repeated helpers
-- fragmented functions
-- unnecessary complications
-- tricky code
-- missing tests
-- weak verification
-- JSKIT convention violations
+Do not create commits, branches, pull requests, merges, or worktree cleanup yourself. JSKIT session owns those steps.
 
-Once you are done, provide a list ordered by priority, with a proposal on how to fix each important issue. If there are no important findings, say so explicitly and list any residual risk.
+When finished, report findings ordered by severity, fixes made, changed files, checks run, and anything still unverified. If there are no important findings, say so explicitly and list residual risk.

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

@@ -1,9 +1,13 @@
-User check {{review_pass}} for session {{session_id}}.
+User check for session {{session_id}}.
 
 The code should already be built or runnable according to the implementation instructions.
 
-Ask the user to test the changed behavior in the app and report whether it works as intended.
+Ask the user to test the changed behavior in the app and report whether it works as intended. Be specific about the user-visible behavior, route, command, or workflow to inspect.
 
-If the user finds a problem, diagnose it and fix it in this worktree. If the behavior works, tell the user to run:
+If the user finds a problem, diagnose the root cause and fix it in this worktree. Keep the fix scoped. Reuse JSKIT helpers, generated seams, and package workflows where they apply.
+
+If the behavior works, tell the user to run:
 
 jskit session {{session_id}} step --user-check passed
+
+Do not commit, push, create a PR, merge, or clean up the worktree yourself. JSKIT session owns those steps.