@jskit-ai/jskit-cli 0.2.79 → 0.2.81

package/src/server/core/commandCatalog.js

@@ -9,7 +9,9 @@ const OPTION_FLAG_LABELS = Object.freeze({
   checkDiLabels: "--check-di-labels",
   verbose: "--verbose",
   json: "--json",
-  all: "--all"
+  all: "--all",
+  abandoned: "--abandoned",
+  completed: "--completed"
 });
 
 const PARSED_BOOLEAN_OPTION_KEYS = Object.freeze(Object.keys(OPTION_FLAG_LABELS));
@@ -198,6 +200,94 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     allowedValueOptionNames: Object.freeze([]),
     canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
   }),
+  session: Object.freeze({
+    command: "session",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Run file-backed JSKIT issue sessions.",
+    minimalUse: "jskit session create",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "create | <sessionId>",
+        description: "Create a session, inspect a session, or run a session subcommand."
+      }),
+      Object.freeze({
+        name: "[step|abandon|adopt-codex-thread]",
+        description: "Run the next step, inspect a diff, abandon a session, or attach a Codex thread id."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Active session state lives in .jskit/sessions/active/<session_id> under the current target app.",
+      "Session worktrees live in .jskit/sessions/active/<session_id>/worktree.",
+      "The session id is timestamp-based and is the primary key.",
+      "Bare list output includes active sessions only; use --abandoned, --completed, or --all for archived sessions.",
+      "Use --json for the stable machine-readable contract consumed by JSKIT AI Studio.",
+      "Use --issue - to read approved issue body from stdin.",
+      "Use --issue-title when the approved issue title is separate from the body.",
+      "Use --plan - to read the approved implementation plan from stdin."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Manual CLI flow",
+        lines: Object.freeze([
+          "jskit session create",
+          "jskit session 2026-05-11_21-42-08 step",
+          "jskit session 2026-05-11_21-42-08 step --prompt \"Fix the customer filters\"",
+          "jskit session 2026-05-11_21-42-08 step --issue-title \"Fix customer filters\" --issue -",
+          "jskit session 2026-05-11_21-42-08 step --plan -",
+          "jskit session 2026-05-11_21-42-08 diff --json"
+        ])
+      })
+    ]),
+    fullUse:
+      "jskit session [create|<sessionId>] [step|diff|abandon|adopt-codex-thread] [--prompt <text>] [--issue-title <text>|--issue-title-file <path>] [--issue <text>|--issue-file <path>] [--plan <text>|--plan-file <path>] [--user-check <passed|failed>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandSession",
+    allowedFlagKeys: Object.freeze(["json", "abandoned", "completed", "all"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => Array.isArray(positional) && positional.length > 0
+  }),
+  blueprint: Object.freeze({
+    command: "blueprint",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Read, prompt, or set the app-level JSKIT blueprint.",
+    minimalUse: "jskit blueprint",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "[prompt|set]",
+        description: "Without a subcommand, prints the saved app blueprint. prompt renders the AI prompt; set writes the approved blueprint."
+      })
+    ]),
+    defaults: Object.freeze([
+      "The app blueprint is product-level app state, not a feature-session step.",
+      "The saved blueprint lives at .jskit/APP_BLUEPRINT.md in the current target app.",
+      "Project prompt overrides live at .jskit/prompts/app_blueprint.md.",
+      "Use --json for a stable machine-readable response."
+    ]),
+    examples: Object.freeze([
+      Object.freeze({
+        label: "Manual blueprint flow",
+        lines: Object.freeze([
+          "jskit blueprint prompt --brief \"A field app for customer visits\"",
+          "jskit blueprint set --blueprint -",
+          "jskit blueprint --json"
+        ])
+      })
+    ]),
+    fullUse:
+      "jskit blueprint [prompt|set] [--brief <text>|--brief-file <path>] [--blueprint <text>|--blueprint-file <path>] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandBlueprint",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => {
+      const subcommand = String(Array.isArray(positional) ? positional[0] || "" : "").trim();
+      return subcommand === "prompt" || subcommand === "set";
+    }
+  }),
   add: Object.freeze({
     command: "add",
     aliases: Object.freeze([]),

package/src/server/core/createCommandHandlers.js

@@ -6,6 +6,8 @@ import { createAppCommands } from "../commandHandlers/app.js";
 import { createMobileCommands } from "../commandHandlers/mobile.js";
 import { createHealthCommands } from "../commandHandlers/health.js";
 import { createCompletionCommands } from "../commandHandlers/completion.js";
+import { createSessionCommands } from "../commandHandlers/session.js";
+import { createBlueprintCommands } from "../commandHandlers/blueprint.js";
 
 function createCommandHandlers(deps = {}) {
   const shared = createCommandHandlerShared(deps);
@@ -29,6 +31,8 @@ function createCommandHandlers(deps = {}) {
   const { commandMobile } = createMobileCommands(commandContext, { commandAdd });
   const { commandDoctor, commandLintDescriptors } = createHealthCommands(commandContext);
   const { commandCompletion } = createCompletionCommands(commandContext);
+  const { commandSession } = createSessionCommands(commandContext);
+  const { commandBlueprint } = createBlueprintCommands(commandContext);
 
   return {
     commandList,
@@ -46,7 +50,9 @@ function createCommandHandlers(deps = {}) {
     commandUpdate,
     commandRemove,
     commandDoctor,
-    commandLintDescriptors
+    commandLintDescriptors,
+    commandSession,
+    commandBlueprint
   };
 }
 

package/src/server/index.js

@@ -1 +1,3 @@
 export { runCli } from "./core/createCliRunner.js";
+export * from "./sessionRuntime.js";
+export * from "./appBlueprint.js";

package/src/server/sessionRuntime/constants.js

@@ -0,0 +1,320 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SESSION_STATUS = Object.freeze({
+  ABANDONED: "abandoned",
+  BLOCKED: "blocked",
+  FAILED: "failed",
+  FINISHED: "finished",
+  PENDING: "pending",
+  RUNNING: "running",
+  WAITING_FOR_USER: "waiting_for_user"
+});
+
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:-[a-z0-9]{4})?$/u;
+const SESSION_STATE_RELATIVE_PATH = ".jskit/sessions";
+const PROMPT_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "prompts");
+
+const INPUT_NONE = Object.freeze({ type: "none" });
+const ISSUE_TITLE_INPUT = Object.freeze({
+  extract: "issue_title",
+  formatHint: "text",
+  label: "Approved issue title",
+  name: "issueTitle",
+  required: true,
+  type: "text"
+});
+const ISSUE_TEXT_INPUT = Object.freeze({
+  extract: "issue_text",
+  formatHint: "markdown",
+  label: "Approved issue body",
+  multiline: true,
+  name: "issue",
+  required: true,
+  type: "text"
+});
+const ISSUE_DRAFT_INPUT = Object.freeze({
+  fields: Object.freeze([
+    ISSUE_TITLE_INPUT,
+    ISSUE_TEXT_INPUT
+  ]),
+  type: "object"
+});
+const ISSUE_TITLE_OUTPUT = Object.freeze({
+  extract: "issue_title",
+  field: "issueTitle",
+  formatHint: "text",
+  label: "Issue title",
+  required: true
+});
+const ISSUE_TEXT_OUTPUT = Object.freeze({
+  extract: "issue_text",
+  field: "issue",
+  formatHint: "markdown",
+  label: "Issue body",
+  multiline: true,
+  required: true
+});
+const PLAN_INPUT = Object.freeze({
+  extract: "plan",
+  formatHint: "markdown",
+  label: "Approved plan",
+  multiline: true,
+  name: "plan",
+  required: true,
+  type: "text"
+});
+const PLAN_OUTPUT = Object.freeze({
+  extract: "plan",
+  field: "plan",
+  formatHint: "markdown",
+  label: "Plan",
+  multiline: true,
+  required: true
+});
+const USER_CHECK_INPUT = Object.freeze({
+  label: "User check result",
+  name: "userCheck",
+  options: Object.freeze([
+    Object.freeze({ label: "Passed", value: "passed" }),
+    Object.freeze({ label: "Failed", value: "failed" })
+  ]),
+  required: true,
+  type: "choice"
+});
+function codexHandoff(expectedOutput, {
+  autoInject = false,
+  promptActionLabel = ""
+} = {}) {
+  const expectedOutputs = Object.freeze(Array.isArray(expectedOutput) ? [...expectedOutput] : [expectedOutput]);
+  return Object.freeze({
+    ...(autoInject ? { autoInject: true } : {}),
+    expectedOutput: expectedOutputs[expectedOutputs.length - 1] || null,
+    expectedOutputs,
+    mode: "inject_prompt",
+    promptField: "prompt",
+    ...(promptActionLabel ? { promptActionLabel } : {})
+  });
+}
+
+const PLAN_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Execute plan"
+});
+const REVIEW_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Start review"
+});
+
+function defineStep({
+  buttonLabel,
+  codex = undefined,
+  description,
+  id,
+  input = INPUT_NONE,
+  kind = "automatic",
+  label,
+  nextCommandTemplate = "jskit session {{session_id}} step",
+  preconditions = [],
+  utilityActions = []
+}) {
+  return Object.freeze({
+    buttonLabel,
+    codex,
+    description,
+    id,
+    input,
+    kind,
+    label,
+    nextCommandTemplate,
+    preconditions: Object.freeze([...preconditions]),
+    utilityActions: Object.freeze([...utilityActions])
+  });
+}
+
+const STEP_DEFINITIONS = Object.freeze([
+  defineStep({
+    buttonLabel: "Create session",
+    description: "Create the filesystem-backed session record.",
+    id: "session_created",
+    label: "Session created"
+  }),
+  defineStep({
+    buttonLabel: "Create worktree",
+    description: "Create the isolated branch and worktree for this session.",
+    id: "worktree_created",
+    label: "Worktree created",
+    preconditions: ["session_exists", "git_repository", "git_current_branch"]
+  }),
+  defineStep({
+    buttonLabel: "Install dependencies",
+    description: "Install Node dependencies inside the session worktree before Codex starts.",
+    id: "dependencies_installed",
+    label: "Dependencies installed",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Submit prompt to Codex",
+    description: "Capture the initial change request and send it to Codex to draft a GitHub issue.",
+    id: "issue_prompt_rendered",
+    input: Object.freeze({
+      label: "What should change?",
+      multiline: true,
+      name: "prompt",
+      placeholder: "Describe the feature, bug, or change request.",
+      required: true,
+      type: "text"
+    }),
+    kind: "human_input",
+    label: "Initial issue prompt",
+    nextCommandTemplate: "jskit session {{session_id}} step --prompt \"<what should change>\"",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save issue draft",
+    codex: codexHandoff([
+      ISSUE_TITLE_OUTPUT,
+      ISSUE_TEXT_OUTPUT
+    ]),
+    description: "Save the approved issue title and body drafted by Codex.",
+    id: "issue_drafted",
+    input: ISSUE_DRAFT_INPUT,
+    kind: "codex_output",
+    label: "Issue drafted",
+    nextCommandTemplate: "jskit session {{session_id}} step --issue -",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Create GitHub issue",
+    description: "Create the GitHub issue from the approved draft.",
+    id: "issue_created",
+    label: "Issue created",
+    preconditions: ["session_exists", "issue_text_exists", "github_auth", "github_origin"]
+  }),
+  defineStep({
+    buttonLabel: "Execute plan",
+    codex: codexHandoff(PLAN_OUTPUT),
+    description: "Save the approved implementation plan, comment it on the GitHub issue, and submit it to Codex.",
+    id: "plan_made",
+    input: PLAN_INPUT,
+    kind: "codex_output",
+    label: "Plan execution",
+    nextCommandTemplate: "jskit session {{session_id}} step --plan -",
+    preconditions: ["session_exists", "issue_text_exists", "issue_url_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Accept changes",
+    description: "Review the worktree diff and accept the changes as ready to commit.",
+    id: "implementation_changes_accepted",
+    kind: "user_check",
+    label: "Changes accepted",
+    preconditions: ["session_exists", "worktree_exists"],
+    utilityActions: Object.freeze([
+      Object.freeze({
+        id: "session_diff",
+        kind: "diff",
+        label: "Review changes",
+        nextCommandTemplate: "jskit session {{session_id}} diff"
+      })
+    ])
+  }),
+  defineStep({
+    buttonLabel: "Commit implementation",
+    description: "Commit the accepted implementation changes in the session worktree.",
+    id: "implementation_changes_committed",
+    label: "Changes committed",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Start review",
+    description: "Submit the code review prompt to Codex for the committed changes.",
+    id: "review_prompt_rendered",
+    kind: "codex_prompt",
+    label: "Review execution",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Accept review changes",
+    description: "Review the post-review worktree diff and accept it as ready to commit.",
+    id: "review_changes_accepted",
+    kind: "user_check",
+    label: "Review changes accepted",
+    preconditions: ["session_exists", "worktree_exists"],
+    utilityActions: Object.freeze([
+      Object.freeze({
+        id: "session_diff",
+        kind: "diff",
+        label: "Review changes",
+        nextCommandTemplate: "jskit session {{session_id}} diff"
+      })
+    ])
+  }),
+  defineStep({
+    buttonLabel: "Commit review changes",
+    description: "Commit accepted review changes, or record that no review changes were needed.",
+    id: "review_changes_committed",
+    label: "Review changes committed",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Save user check",
+    description: "Record whether the user’s manual check passed.",
+    id: "user_check_completed",
+    input: USER_CHECK_INPUT,
+    kind: "user_check",
+    label: "User check",
+    nextCommandTemplate: "jskit session {{session_id}} step --user-check passed",
+    preconditions: ["session_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Run verification",
+    description: "Run the project verification command in the session worktree.",
+    id: "doctor_run",
+    label: "Verification run",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Push branch and create PR",
+    description: "Push the session branch to origin and create a GitHub pull request.",
+    id: "pr_created",
+    label: "Branch pushed, PR created",
+    preconditions: ["session_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Merge PR and remove worktree",
+    description: "Merge the pull request, close the GitHub issue, and remove the session worktree.",
+    id: "pr_merged",
+    label: "PR merged, worktree removed",
+    preconditions: ["session_exists", "pr_url_exists", "worktree_exists"]
+  }),
+  defineStep({
+    buttonLabel: "Finish session",
+    description: "Write the final receipt and archive the completed session.",
+    id: "session_finished",
+    label: "Session finished",
+    preconditions: ["session_exists"]
+  })
+]);
+
+const STEP_IDS = Object.freeze(STEP_DEFINITIONS.map((step) => step.id));
+const STEP_LABEL_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step.label])));
+const STEP_DEFINITION_BY_ID = Object.freeze(Object.fromEntries(STEP_DEFINITIONS.map((step) => [step.id, step])));
+const STEP_PRECONDITION_NAMES = Object.freeze(Object.fromEntries(
+  STEP_DEFINITIONS
+    .filter((step) => step.id !== "session_created")
+    .map((step) => [step.id, step.preconditions])
+));
+
+export {
+  PROMPT_DIRECTORY,
+  SESSION_ID_PATTERN,
+  SESSION_STATUS,
+  STEP_DEFINITION_BY_ID,
+  STEP_DEFINITIONS,
+  STEP_IDS,
+  STEP_LABEL_BY_ID,
+  STEP_PRECONDITION_NAMES,
+  PLAN_EXECUTION_CODEX_HANDOFF,
+  REVIEW_EXECUTION_CODEX_HANDOFF,
+  SESSION_STATE_RELATIVE_PATH
+};

package/src/server/sessionRuntime/io.js

@@ -0,0 +1,97 @@
+import { execFile } from "node:child_process";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+function normalizeText(value) {
+  return String(value || "").trim();
+}
+
+function timestampForReceipt(now = new Date()) {
+  return now.toISOString();
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readTextIfExists(filePath) {
+  if (!filePath || !(await fileExists(filePath))) {
+    return "";
+  }
+  return readFile(filePath, "utf8");
+}
+
+async function readTrimmedFile(filePath) {
+  return normalizeText(await readTextIfExists(filePath));
+}
+
+async function writeTextFile(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${String(value || "").replace(/\s*$/u, "")}\n`, "utf8");
+}
+
+async function runCommand(command, args = [], { cwd, env = {}, timeout = 30000 } = {}) {
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd,
+      env: {
+        ...process.env,
+        ...env
+      },
+      maxBuffer: 1024 * 1024 * 10,
+      timeout
+    });
+    return {
+      exitCode: 0,
+      ok: true,
+      output: String([result.stdout, result.stderr].filter(Boolean).join("\n")).trim(),
+      stderr: String(result.stderr || "").trim(),
+      stdout: String(result.stdout || "").trim()
+    };
+  } catch (error) {
+    const stdout = String(error?.stdout || "").trim();
+    const stderr = String(error?.stderr || "").trim();
+    return {
+      exitCode: typeof error?.code === "number" ? error.code : 1,
+      ok: false,
+      output: String(error?.message || [stdout, stderr].filter(Boolean).join("\n")).trim(),
+      stderr,
+      stdout
+    };
+  }
+}
+
+async function runGit(targetRoot, args = [], options = {}) {
+  return runCommand("git", args, {
+    cwd: targetRoot,
+    ...options
+  });
+}
+
+async function runGitInWorktree(worktree, args = [], options = {}) {
+  return runCommand("git", args, {
+    cwd: worktree,
+    ...options
+  });
+}
+
+export {
+  fileExists,
+  normalizeText,
+  readTextIfExists,
+  readTrimmedFile,
+  runCommand,
+  runGit,
+  runGitInWorktree,
+  timestampForReceipt,
+  writeTextFile
+};