@jskit-ai/jskit-cli 0.2.79 → 0.2.81

package/src/server/sessionRuntime/paths.js

@@ -0,0 +1,163 @@
+import { mkdir, rename } from "node:fs/promises";
+import path from "node:path";
+import {
+  SESSION_ID_PATTERN,
+  SESSION_STATE_RELATIVE_PATH
+} from "./constants.js";
+import {
+  fileExists,
+  normalizeText
+} from "./io.js";
+
+function formatDatePart(value) {
+  return String(value).padStart(2, "0");
+}
+
+function createSessionId(now = new Date()) {
+  const year = now.getFullYear();
+  const month = formatDatePart(now.getMonth() + 1);
+  const day = formatDatePart(now.getDate());
+  const hour = formatDatePart(now.getHours());
+  const minute = formatDatePart(now.getMinutes());
+  const second = formatDatePart(now.getSeconds());
+  return `${year}-${month}-${day}_${hour}-${minute}-${second}`;
+}
+
+async function createAvailableSessionId(targetRoot, now = new Date()) {
+  const baseSessionId = createSessionId(now);
+  const basePaths = resolveSessionPaths({ targetRoot, sessionId: baseSessionId });
+  if (
+    !(await fileExists(basePaths.sessionRoot)) &&
+    !(await fileExists(basePaths.completedSessionRoot)) &&
+    !(await fileExists(basePaths.abandonedSessionRoot))
+  ) {
+    return baseSessionId;
+  }
+
+  for (let index = 1; index <= 36 ** 4 - 1; index += 1) {
+    const suffix = index.toString(36).padStart(4, "0");
+    const candidate = `${baseSessionId}-${suffix}`;
+    const candidatePaths = resolveSessionPaths({ targetRoot, sessionId: candidate });
+    if (
+      !(await fileExists(candidatePaths.sessionRoot)) &&
+      !(await fileExists(candidatePaths.completedSessionRoot)) &&
+      !(await fileExists(candidatePaths.abandonedSessionRoot))
+    ) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`No available session id found for timestamp ${baseSessionId}.`);
+}
+
+function isValidSessionId(sessionId = "") {
+  return SESSION_ID_PATTERN.test(normalizeText(sessionId));
+}
+
+function normalizeSessionId(sessionId = "") {
+  const normalized = normalizeText(sessionId);
+  if (!isValidSessionId(normalized)) {
+    throw new Error(`Invalid session id "${sessionId}". Expected YYYY-MM-DD_HH-MM-SS.`);
+  }
+  return normalized;
+}
+
+function resolveSessionPaths({ targetRoot, sessionId = "" } = {}) {
+  const normalizedTargetRoot = path.resolve(normalizeText(targetRoot) || process.cwd());
+  const sessionStateRoot = path.join(normalizedTargetRoot, SESSION_STATE_RELATIVE_PATH);
+  const sessionsRoot = path.join(sessionStateRoot, "active");
+  const completedSessionsRoot = path.join(sessionStateRoot, "completed");
+  const abandonedSessionsRoot = path.join(sessionStateRoot, "abandoned");
+  const normalizedSessionId = sessionId ? normalizeSessionId(sessionId) : "";
+  const sessionRoot = normalizedSessionId ? path.join(sessionsRoot, normalizedSessionId) : "";
+  const worktree = normalizedSessionId ? path.join(sessionRoot, "worktree") : "";
+  const branch = normalizedSessionId ? `jskit-studio/${normalizedSessionId}` : "";
+
+  return Object.freeze({
+    abandonedSessionRoot: normalizedSessionId ? path.join(abandonedSessionsRoot, normalizedSessionId) : "",
+    abandonedSessionsRoot,
+    branch,
+    completedSessionRoot: normalizedSessionId ? path.join(completedSessionsRoot, normalizedSessionId) : "",
+    completedSessionsRoot,
+    sessionId: normalizedSessionId,
+    sessionRoot,
+    sessionsRoot,
+    sessionStateRoot,
+    targetRoot: normalizedTargetRoot,
+    worktree
+  });
+}
+
+async function resolveExistingSessionRoot(paths) {
+  if (paths.archive && await fileExists(paths.sessionRoot)) {
+    return {
+      archive: paths.archive,
+      root: paths.sessionRoot
+    };
+  }
+  if (await fileExists(paths.sessionRoot)) {
+    return {
+      archive: "active",
+      root: paths.sessionRoot
+    };
+  }
+  if (await fileExists(paths.completedSessionRoot)) {
+    return {
+      archive: "completed",
+      root: paths.completedSessionRoot
+    };
+  }
+  if (await fileExists(paths.abandonedSessionRoot)) {
+    return {
+      archive: "abandoned",
+      root: paths.abandonedSessionRoot
+    };
+  }
+  return {
+    archive: "",
+    root: ""
+  };
+}
+
+async function pathsForExistingSession(paths) {
+  const existing = await resolveExistingSessionRoot(paths);
+  if (!existing.root || existing.root === paths.sessionRoot) {
+    return paths;
+  }
+  return Object.freeze({
+    ...paths,
+    archive: existing.archive,
+    sessionRoot: existing.root
+  });
+}
+
+async function archiveSession(paths, archive) {
+  const archiveRoot = archive === "completed" ? paths.completedSessionRoot : paths.abandonedSessionRoot;
+  if (!archiveRoot || paths.sessionRoot === archiveRoot) {
+    return paths;
+  }
+  if (!(await fileExists(paths.sessionRoot))) {
+    return pathsForExistingSession(paths);
+  }
+  if (await fileExists(archiveRoot)) {
+    throw new Error(`Cannot archive session ${paths.sessionId}; target already exists: ${archiveRoot}`);
+  }
+  await mkdir(path.dirname(archiveRoot), { recursive: true });
+  await rename(paths.sessionRoot, archiveRoot);
+  return Object.freeze({
+    ...paths,
+    archive,
+    sessionRoot: archiveRoot
+  });
+}
+
+export {
+  archiveSession,
+  createAvailableSessionId,
+  createSessionId,
+  isValidSessionId,
+  normalizeSessionId,
+  resolveExistingSessionRoot,
+  resolveSessionPaths,
+  pathsForExistingSession
+};

package/src/server/sessionRuntime/preconditions.js

@@ -0,0 +1,362 @@
+import {
+  access,
+  appendFile,
+  mkdir
+} 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";
+import {
+  hasWorktree
+} from "./worktrees.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 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 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: `jskit session ${paths.sessionId} step`
+    }),
+    precondition: createPrecondition({
+      id: "issue_url_exists",
+      ok: false,
+      message: "GitHub issue URL exists."
+    })
+  };
+}
+
+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,
+  assertIssueTextExists,
+  assertIssueUrlExists,
+  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,52 @@
+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, 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. 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:
+
+[app_blueprint]
+# App Blueprint
+...
+[/app_blueprint]

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

@@ -0,0 +1,26 @@
+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 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/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.