@jskit-ai/jskit-cli 0.2.78 → 0.2.80

package/src/server/sessionRuntime/preconditions.js

@@ -0,0 +1,372 @@
+import {
+  access,
+  appendFile,
+  mkdir,
+  stat
+} from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import {
+  SESSION_STATE_RELATIVE_PATH
+} from "./constants.js";
+import {
+  createError,
+  createPrecondition
+} from "./responses.js";
+import {
+  readTextIfExists,
+  readTrimmedFile,
+  runCommand,
+  runGit
+} from "./io.js";
+import {
+  resolveExistingSessionRoot
+} from "./paths.js";
+
+async function assertTargetRootWritable(targetRoot) {
+  try {
+    await access(targetRoot, fsConstants.R_OK | fsConstants.W_OK);
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "target_root_writable",
+        ok: true,
+        message: "Target root exists and is readable/writable."
+      })
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: createError({
+        code: "target_root_not_writable",
+        message: `Target root is not readable/writable: ${error?.message || error}`,
+        repairCommand: `test -w ${targetRoot}`
+      }),
+      precondition: createPrecondition({
+        id: "target_root_writable",
+        ok: false,
+        message: "Target root exists and is readable/writable."
+      })
+    };
+  }
+}
+
+async function resolveGitCommonDirectory(targetRoot) {
+  const result = await runGit(targetRoot, ["rev-parse", "--git-common-dir"]);
+  if (!result.ok || !result.stdout) {
+    return "";
+  }
+  return path.resolve(targetRoot, result.stdout);
+}
+
+async function assertGitRepository(targetRoot) {
+  const result = await runGit(targetRoot, ["rev-parse", "--is-inside-work-tree"]);
+  if (result.ok && result.stdout === "true") {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "git_repository",
+        ok: true,
+        message: "Target root is inside a git work tree."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "git_repository_missing",
+      message: "Target root is not inside a git work tree.",
+      repairCommand: "git init"
+    }),
+    precondition: createPrecondition({
+      id: "git_repository",
+      ok: false,
+      message: "Target root is inside a git work tree."
+    })
+  };
+}
+
+async function assertGitCurrentBranch(targetRoot) {
+  const [branchResult, headResult] = await Promise.all([
+    runGit(targetRoot, ["branch", "--show-current"]),
+    runGit(targetRoot, ["rev-parse", "--verify", "HEAD"])
+  ]);
+  if (branchResult.ok && branchResult.stdout && headResult.ok) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "git_current_branch",
+        ok: true,
+        message: "Target repository has a named current branch with an initial commit."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "git_current_branch_missing",
+      message: "Target repository does not have a named current branch with an initial commit.",
+      repairCommand: "git checkout -b main && git add . && git commit -m \"Initial commit\""
+    }),
+    precondition: createPrecondition({
+      id: "git_current_branch",
+      ok: false,
+      message: "Target repository has a named current branch with an initial commit."
+    })
+  };
+}
+
+async function assertGhAuth(targetRoot) {
+  const result = await runCommand("gh", ["auth", "status"], {
+    cwd: targetRoot,
+    timeout: 15000
+  });
+  if (result.ok) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "github_auth",
+        ok: true,
+        message: "GitHub CLI is authenticated."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "github_auth_missing",
+      message: "GitHub CLI is not authenticated.",
+      repairCommand: "gh auth login"
+    }),
+    precondition: createPrecondition({
+      id: "github_auth",
+      ok: false,
+      message: "GitHub CLI is authenticated."
+    })
+  };
+}
+
+async function assertGithubOrigin(targetRoot) {
+  const result = await runGit(targetRoot, ["remote", "get-url", "origin"]);
+  if (result.ok && /github\.com[:/]/u.test(result.stdout)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "github_origin",
+        ok: true,
+        message: "Origin remote points at GitHub."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "github_origin_missing",
+      message: "Origin remote is missing or is not a GitHub remote.",
+      repairCommand: "git remote add origin https://github.com/<owner>/<repo>.git"
+    }),
+    precondition: createPrecondition({
+      id: "github_origin",
+      ok: false,
+      message: "Origin remote points at GitHub."
+    })
+  };
+}
+
+async function applyPreconditions(paths, checks = []) {
+  const preconditions = [];
+  for (const check of checks) {
+    const result = await check();
+    if (result?.precondition) {
+      preconditions.push(result.precondition);
+    }
+    if (result?.ok !== true) {
+      return {
+        ok: false,
+        error: result.error,
+        preconditions
+      };
+    }
+  }
+  void paths;
+  return {
+    ok: true,
+    preconditions
+  };
+}
+
+async function ensureStudioGitExclude(targetRoot) {
+  const gitCommonDirectory = await resolveGitCommonDirectory(targetRoot);
+  if (!gitCommonDirectory) {
+    return;
+  }
+  const excludePath = path.join(gitCommonDirectory, "info", "exclude");
+  await mkdir(path.dirname(excludePath), { recursive: true });
+  const current = await readTextIfExists(excludePath);
+  const lines = current.split(/\r?\n/u).map((line) => line.trim());
+  if (!lines.includes(`${SESSION_STATE_RELATIVE_PATH}/`)) {
+    await appendFile(excludePath, `${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${SESSION_STATE_RELATIVE_PATH}/\n`, "utf8");
+  }
+}
+
+async function assertSessionExists(paths) {
+  const existing = await resolveExistingSessionRoot(paths);
+  if (existing.root) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "session_exists",
+        ok: true,
+        message: "Session state directory exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "session_missing",
+      message: `Session does not exist: ${paths.sessionId}`,
+      repairCommand: "jskit session create"
+    }),
+    precondition: createPrecondition({
+      id: "session_exists",
+      ok: false,
+      message: "Session state directory exists."
+    })
+  };
+}
+
+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) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "issue_artifacts",
+        ok: true,
+        message: "Issue text and GitHub issue URL exist."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "issue_artifacts_missing",
+      message: "Issue text and GitHub issue URL are required.",
+      repairCommand: `jskit session ${paths.sessionId} step`
+    }),
+    precondition: createPrecondition({
+      id: "issue_artifacts",
+      ok: false,
+      message: "Issue text and GitHub issue URL exist."
+    })
+  };
+}
+
+async function assertIssueTextExists(paths) {
+  const issueText = await readTrimmedFile(path.join(paths.sessionRoot, "issue.md"));
+  if (issueText) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "issue_text_exists",
+        ok: true,
+        message: "Issue text 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 -`
+    }),
+    precondition: createPrecondition({
+      id: "issue_text_exists",
+      ok: false,
+      message: "Issue text 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 {
+      ok: true,
+      precondition: createPrecondition({
+        id: "worktree_exists",
+        ok: true,
+        message: "Session worktree exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "worktree_missing",
+      message: "Session worktree does not exist.",
+      repairCommand: `jskit session ${paths.sessionId} step`
+    }),
+    precondition: createPrecondition({
+      id: "worktree_exists",
+      ok: false,
+      message: "Session worktree exists."
+    })
+  };
+}
+
+async function assertPrUrlExists(paths) {
+  const prUrl = await readTrimmedFile(path.join(paths.sessionRoot, "pr_url"));
+  if (prUrl) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "pr_url_exists",
+        ok: true,
+        message: "PR URL exists."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "pr_url_missing",
+      message: "Cannot merge before pr_url exists.",
+      repairCommand: `jskit session ${paths.sessionId} step`
+    }),
+    precondition: createPrecondition({
+      id: "pr_url_exists",
+      ok: false,
+      message: "PR URL exists."
+    })
+  };
+}
+
+export {
+  applyPreconditions,
+  assertGhAuth,
+  assertGitCurrentBranch,
+  assertGitRepository,
+  assertGithubOrigin,
+  assertIssueArtifacts,
+  assertIssueTextExists,
+  assertPrUrlExists,
+  assertSessionExists,
+  assertTargetRootWritable,
+  assertWorktreeExists,
+  ensureStudioGitExclude,
+  hasWorktree
+};

package/src/server/sessionRuntime/promptRenderer.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import {
+  PROMPT_DIRECTORY,
+  SESSION_STATE_RELATIVE_PATH
+} from "./constants.js";
+import {
+  fileExists,
+  normalizeText,
+  readTextIfExists
+} from "./io.js";
+
+async function readPromptTemplate(targetRoot, name) {
+  const normalizedName = normalizeText(name);
+  const overridePath = path.join(targetRoot, SESSION_STATE_RELATIVE_PATH, "prompts", normalizedName);
+  if (await fileExists(overridePath)) {
+    return readTextIfExists(overridePath);
+  }
+  return readTextIfExists(path.join(PROMPT_DIRECTORY, normalizedName));
+}
+
+function renderTemplate(source, values = {}) {
+  return String(source || "").replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/gu, (_match, key) => {
+    return String(values[key] ?? "");
+  });
+}
+
+async function renderPrompt(paths, templateName, values = {}) {
+  const template = await readPromptTemplate(paths.targetRoot, templateName);
+  return renderTemplate(template, {
+    branch: paths.branch,
+    session_id: paths.sessionId,
+    worktree: paths.worktree,
+    ...values
+  }).trim();
+}
+
+export {
+  readPromptTemplate,
+  renderPrompt,
+  renderTemplate
+};

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

@@ -0,0 +1,28 @@
+Create a durable JSKIT app blueprint from this app brief.
+
+App brief:
+
+{{app_brief}}
+
+Produce a concise but useful app-level blueprint. It must describe product intent, not implementation steps for the current issue.
+
+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.
+- 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.
+- Important non-goals and constraints.
+- First useful screen and what it should show.
+- Settings, admin, and operator expectations when relevant.
+
+If the brief is ambiguous, state the assumption in the blueprint instead of asking questions.
+
+When the blueprint is ready, output only the final markdown surrounded by these exact markers:
+
+[app_blueprint]
+# App Blueprint
+...
+[/app_blueprint]

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

@@ -0,0 +1,15 @@
+The JSKIT session doctor or verification step failed.
+
+Session:
+
+{{session_id}}
+
+Worktree:
+
+{{worktree}}
+
+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.

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

@@ -0,0 +1,8 @@
+Codex thread id: {{codex_thread_id}}
+Issue session status: finished
+PR: {{pr_url}}
+Local transcript: {{transcript_log}}
+
+Summary:
+
+Session {{session_id}} finished and merged.

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

@@ -0,0 +1,25 @@
+Work only in this session worktree:
+
+{{worktree}}
+
+Branch:
+
+{{branch}}
+
+Issue URL:
+
+{{issue_url}}
+
+Issue:
+
+{{issue_text}}
+
+Instructions:
+
+- Keep changes scoped to this issue.
+- Do not touch unrelated files.
+- Prefer existing JSKIT package/runtime seams before adding local helpers.
+- Ask the user when blocked by product or architecture ambiguity.
+- Run relevant checks before reporting completion.
+- Do not push, open a PR, merge, or remove the worktree unless JSKIT Studio explicitly instructs it.
+- Report changed files and verification when the implementation is ready.

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

@@ -0,0 +1,13 @@
+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.
+
+When the issue text is ready, output only the final issue body surrounded by these exact markers:
+
+[issue_text]
+<issue title and body>
+[/issue_text]
+
+The issue should be concrete, scoped, and implementation-ready. Include acceptance criteria when they are useful.

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

@@ -0,0 +1,15 @@
+The JSKIT session PR operation failed.
+
+Session:
+
+{{session_id}}
+
+Worktree:
+
+{{worktree}}
+
+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.

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

@@ -0,0 +1,22 @@
+Review pass {{review_pass}} for session {{session_id}}.
+
+{{review_pass_note}}
+
+Changed files from the latest commit:
+
+{{changed_files}}
+
+Check through the changed code and see if the changes are done without problems:
+
+- slop
+- repeated code
+- ownership issues
+- repeated helpers
+- fragmented functions
+- unnecessary complications
+- tricky code
+- missing tests
+- weak verification
+- JSKIT convention violations
+
+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.

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

@@ -0,0 +1,9 @@
+User check {{review_pass}} 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.
+
+If the user finds a problem, diagnose it and fix it in this worktree. If the behavior works, tell the user to run:
+
+jskit session {{session_id}} step --user-check passed