@jskit-ai/jskit-cli 0.2.79 → 0.2.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.79",
+  "version": "0.2.80",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.78",
-    "@jskit-ai/kernel": "0.1.70",
-    "@jskit-ai/shell-web": "0.1.69"
+    "@jskit-ai/jskit-catalog": "0.1.79",
+    "@jskit-ai/kernel": "0.1.71",
+    "@jskit-ai/shell-web": "0.1.70"
   },
   "engines": {
     "node": ">=20 <23"

package/src/server/appBlueprint.js

@@ -0,0 +1,126 @@
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  PROMPT_DIRECTORY
+} from "./sessionRuntime/constants.js";
+import {
+  fileExists,
+  normalizeText,
+  readTextIfExists,
+  writeTextFile
+} from "./sessionRuntime/io.js";
+import {
+  renderTemplate
+} from "./sessionRuntime/promptRenderer.js";
+
+const APP_BLUEPRINT_RELATIVE_PATH = ".jskit/APP_BLUEPRINT.md";
+const APP_PROMPT_OVERRIDE_RELATIVE_ROOT = ".jskit/prompts";
+
+function resolveAppBlueprintPaths(targetRoot = process.cwd()) {
+  const normalizedTargetRoot = path.resolve(normalizeText(targetRoot) || process.cwd());
+  return Object.freeze({
+    appBlueprintPath: path.join(normalizedTargetRoot, APP_BLUEPRINT_RELATIVE_PATH),
+    promptOverrideRoot: path.join(normalizedTargetRoot, APP_PROMPT_OVERRIDE_RELATIVE_ROOT),
+    targetRoot: normalizedTargetRoot
+  });
+}
+
+function extractAppBlueprintText(value = "") {
+  const text = normalizeText(value);
+  const match = /\[app_blueprint\]([\s\S]*?)\[\/app_blueprint\]/u.exec(text);
+  return normalizeText(match ? match[1] : text);
+}
+
+async function readAppPromptTemplate(paths, templateName) {
+  const normalizedName = normalizeText(templateName);
+  const overridePath = path.join(paths.promptOverrideRoot, normalizedName);
+  if (await fileExists(overridePath)) {
+    return readTextIfExists(overridePath);
+  }
+  return readTextIfExists(path.join(PROMPT_DIRECTORY, normalizedName));
+}
+
+async function renderAppBlueprintPrompt({ targetRoot = process.cwd(), appBrief = "" } = {}) {
+  const paths = resolveAppBlueprintPaths(targetRoot);
+  const normalizedBrief = normalizeText(appBrief);
+  if (!normalizedBrief) {
+    return {
+      ok: false,
+      appBlueprintPath: paths.appBlueprintPath,
+      errors: [
+        {
+          code: "app_brief_required",
+          message: "jskit blueprint prompt requires --brief, --brief-file, or --brief -.",
+          repairCommand: "jskit blueprint prompt --brief \"<what app are we building>\""
+        }
+      ],
+      prompt: ""
+    };
+  }
+  const template = await readAppPromptTemplate(paths, "app_blueprint.md");
+  return {
+    ok: true,
+    appBlueprintPath: paths.appBlueprintPath,
+    errors: [],
+    prompt: renderTemplate(template, {
+      app_brief: normalizedBrief
+    }).trim()
+  };
+}
+
+async function readAppBlueprint({ targetRoot = process.cwd() } = {}) {
+  const paths = resolveAppBlueprintPaths(targetRoot);
+  const blueprintText = await readTextIfExists(paths.appBlueprintPath);
+  return {
+    ok: true,
+    appBlueprintPath: paths.appBlueprintPath,
+    blueprintText: blueprintText.trim(),
+    exists: Boolean(blueprintText.trim()),
+    errors: []
+  };
+}
+
+async function writeAppBlueprint({ targetRoot = process.cwd(), appBlueprint = "" } = {}) {
+  const paths = resolveAppBlueprintPaths(targetRoot);
+  const blueprintText = extractAppBlueprintText(appBlueprint);
+  if (!blueprintText) {
+    return {
+      ok: false,
+      appBlueprintPath: paths.appBlueprintPath,
+      blueprintText: "",
+      exists: false,
+      errors: [
+        {
+          code: "app_blueprint_required",
+          message: "jskit blueprint set requires --blueprint, --blueprint-file, or --blueprint -.",
+          repairCommand: "jskit blueprint set --blueprint -"
+        }
+      ]
+    };
+  }
+  await mkdir(path.dirname(paths.appBlueprintPath), { recursive: true });
+  await writeTextFile(paths.appBlueprintPath, blueprintText);
+  return {
+    ok: true,
+    appBlueprintPath: paths.appBlueprintPath,
+    blueprintText,
+    exists: true,
+    errors: []
+  };
+}
+
+async function readTextInputFile(cwd, inputPath) {
+  const resolvedPath = path.resolve(cwd, normalizeText(inputPath));
+  return readFile(resolvedPath, "utf8");
+}
+
+export {
+  APP_BLUEPRINT_RELATIVE_PATH,
+  APP_PROMPT_OVERRIDE_RELATIVE_ROOT,
+  extractAppBlueprintText,
+  readAppBlueprint,
+  readTextInputFile,
+  renderAppBlueprintPrompt,
+  resolveAppBlueprintPaths,
+  writeAppBlueprint
+};

package/src/server/commandHandlers/blueprint.js

@@ -0,0 +1,151 @@
+import {
+  readAppBlueprint,
+  readTextInputFile,
+  renderAppBlueprintPrompt,
+  writeAppBlueprint
+} from "../appBlueprint.js";
+
+function writeJson(stdout, payload) {
+  stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function writeBlueprintText(stdout, payload) {
+  if (payload.prompt) {
+    stdout.write(`${payload.prompt}\n`);
+    return;
+  }
+  if (payload.blueprintText) {
+    stdout.write(`${payload.blueprintText}\n`);
+    return;
+  }
+  stdout.write(`No app blueprint set at ${payload.appBlueprintPath}.\n`);
+}
+
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function resolveTextInput({
+  cwd,
+  fileOption,
+  inlineOptions = {},
+  io = {},
+  stdinOption = "-",
+  textOption
+}) {
+  if (Object.hasOwn(inlineOptions, fileOption)) {
+    const inputFile = String(inlineOptions[fileOption] || "").trim();
+    return inputFile ? readTextInputFile(cwd, inputFile) : "";
+  }
+  if (Object.hasOwn(inlineOptions, textOption)) {
+    const textValue = String(inlineOptions[textOption] ?? "");
+    return textValue === stdinOption ? readStream(io.stdin) : textValue;
+  }
+  return "";
+}
+
+function createBlueprintCommands(ctx = {}) {
+  const { resolveAppRootFromCwd } = ctx;
+
+  async function commandBlueprint({
+    positional = [],
+    options = {},
+    cwd,
+    stdout,
+    io = {}
+  } = {}) {
+    const appRoot = await resolveAppRootFromCwd(cwd);
+    const inlineOptions = options.inlineOptions || {};
+    const subcommand = String(positional[0] || "").trim();
+    let payload;
+
+    try {
+      if (positional.length > 1) {
+        payload = {
+          ok: false,
+          appBlueprintPath: "",
+          errors: [
+            {
+              code: "unexpected_blueprint_argument",
+              message: `Unexpected blueprint argument: ${positional.slice(1).join(" ")}`,
+              repairCommand: "jskit blueprint"
+            }
+          ]
+        };
+      } else if (!subcommand) {
+        payload = await readAppBlueprint({ targetRoot: appRoot });
+      } else if (subcommand === "prompt") {
+        const appBrief = await resolveTextInput({
+          cwd,
+          fileOption: "brief-file",
+          inlineOptions,
+          io,
+          textOption: "brief"
+        });
+        payload = await renderAppBlueprintPrompt({
+          targetRoot: appRoot,
+          appBrief
+        });
+      } else if (subcommand === "set") {
+        const appBlueprint = await resolveTextInput({
+          cwd,
+          fileOption: "blueprint-file",
+          inlineOptions,
+          io,
+          textOption: "blueprint"
+        });
+        payload = await writeAppBlueprint({
+          targetRoot: appRoot,
+          appBlueprint
+        });
+      } else {
+        payload = {
+          ok: false,
+          appBlueprintPath: "",
+          errors: [
+            {
+              code: "unknown_blueprint_subcommand",
+              message: `Unknown blueprint subcommand: ${subcommand}`,
+              repairCommand: "jskit blueprint"
+            }
+          ]
+        };
+      }
+    } catch (error) {
+      payload = {
+        ok: false,
+        appBlueprintPath: "",
+        errors: [
+          {
+            code: "blueprint_input_read_failed",
+            message: String(error?.message || error),
+            repairCommand: "jskit blueprint"
+          }
+        ]
+      };
+    }
+
+    if (options.json) {
+      writeJson(stdout, payload);
+    } else if (payload.ok === false) {
+      for (const error of payload.errors || []) {
+        stdout.write(`[${error.code}] ${error.message}\n`);
+        if (error.repairCommand) {
+          stdout.write(`Repair: ${error.repairCommand}\n`);
+        }
+      }
+    } else {
+      writeBlueprintText(stdout, payload);
+    }
+
+    return payload.ok === false ? 1 : 0;
+  }
+
+  return { commandBlueprint };
+}
+
+export { createBlueprintCommands };

package/src/server/commandHandlers/session.js

@@ -0,0 +1,237 @@
+import { readFile } from "node:fs/promises";
+import {
+  abandonSession,
+  adoptCodexThreadId,
+  buildSessionErrorResponse,
+  createSession,
+  inspectSessionDetails,
+  listSessions,
+  runSessionStep
+} from "../sessionRuntime.js";
+
+function writeJson(stdout, payload) {
+  stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function writeSessionText(stdout, payload) {
+  if (payload.sessions) {
+    stdout.write("JSKIT sessions\n");
+    if (payload.sessions.length < 1) {
+      stdout.write("No sessions found.\n");
+      return;
+    }
+    for (const session of payload.sessions) {
+      stdout.write(`- ${session.sessionId} ${session.status} ${session.currentStep || "done"}\n`);
+    }
+    return;
+  }
+
+  stdout.write(`Session: ${payload.sessionId || "unknown"}\n`);
+  stdout.write(`Status: ${payload.status || "unknown"}\n`);
+  stdout.write(`Current step: ${payload.currentStep || "done"}\n`);
+  if (payload.issueUrl) {
+    stdout.write(`Issue: ${payload.issueUrl}\n`);
+  }
+  if (payload.prUrl) {
+    stdout.write(`PR: ${payload.prUrl}\n`);
+  }
+  if (payload.branch) {
+    stdout.write(`Branch: ${payload.branch}\n`);
+  }
+  if (payload.worktree) {
+    stdout.write(`Worktree: ${payload.worktree}\n`);
+  }
+  if (payload.completedSteps?.length) {
+    stdout.write("Done steps:\n");
+    for (const step of payload.completedSteps) {
+      stdout.write(`- ${step}\n`);
+    }
+  }
+  if (payload.prompt) {
+    stdout.write("\n");
+    stdout.write(payload.prompt);
+    stdout.write("\n");
+  }
+  if (payload.errors?.length) {
+    stdout.write("Errors:\n");
+    for (const error of payload.errors) {
+      stdout.write(`- [${error.code}] ${error.message}\n`);
+      if (error.repairCommand) {
+        stdout.write(`  Repair: ${error.repairCommand}\n`);
+      }
+    }
+  }
+  if (payload.nextCommand) {
+    stdout.write(`Next: ${payload.nextCommand}\n`);
+  }
+}
+
+async function readStream(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function resolveInputFilePath(cwd, filePath) {
+  return filePath.startsWith("/") ? filePath : `${cwd}/${filePath}`;
+}
+
+async function resolveTextInput({
+  codePrefix,
+  fileOption,
+  inlineOptions = {},
+  io = {},
+  repairCommand,
+  cwd,
+  stdinOption,
+  textOption,
+  sessionId
+}) {
+  if (Object.hasOwn(inlineOptions, fileOption)) {
+    const inputFile = String(inlineOptions[fileOption] || "").trim();
+    if (!inputFile) {
+      return { ok: true, value: "" };
+    }
+    const resolvedInputFile = resolveInputFilePath(cwd, inputFile);
+    try {
+      return {
+        ok: true,
+        value: await readFile(resolvedInputFile, "utf8")
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        payload: buildSessionErrorResponse({
+          targetRoot: cwd,
+          sessionId,
+          code: `${codePrefix}_file_read_failed`,
+          message: `Could not read ${codePrefix.replaceAll("_", " ")} file ${resolvedInputFile}: ${error.message}`,
+          repairCommand
+        })
+      };
+    }
+  }
+  if (Object.hasOwn(inlineOptions, textOption)) {
+    const textValue = String(inlineOptions[textOption] ?? "");
+    if (textValue === stdinOption) {
+      return {
+        ok: true,
+        value: await readStream(io.stdin)
+      };
+    }
+    return {
+      ok: true,
+      value: textValue
+    };
+  }
+  return { ok: true, value: "" };
+}
+
+async function resolveStepInputs({
+  inlineOptions = {},
+  io = {},
+  cwd,
+  sessionId
+}) {
+  const issue = await resolveTextInput({
+    codePrefix: "issue",
+    fileOption: "issue-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --issue -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "issue"
+  });
+  if (issue.ok === false) {
+    return issue;
+  }
+
+  return {
+    issue: issue.value,
+    ok: true
+  };
+}
+
+function normalizeStepOptions(inlineOptions = {}) {
+  return {
+    ...inlineOptions,
+    prompt: inlineOptions.prompt,
+    userCheck: inlineOptions["user-check"] || inlineOptions.userCheck
+  };
+}
+
+function createSessionCommands() {
+  return {
+    async commandSession({
+      positional = [],
+      options = {},
+      cwd,
+      stdout,
+      io = {}
+    } = {}) {
+      const [first, second] = positional;
+      const inlineOptions = options.inlineOptions || {};
+      let payload;
+
+      if (!first) {
+        payload = await listSessions({ targetRoot: cwd });
+      } else if (first === "create") {
+        payload = await createSession({ targetRoot: cwd });
+      } else if (second === "step") {
+        const stepInputs = await resolveStepInputs({
+          inlineOptions,
+          io,
+          cwd,
+          sessionId: first
+        });
+        payload = stepInputs.ok === false
+          ? stepInputs.payload
+          : await runSessionStep({
+              targetRoot: cwd,
+              sessionId: first,
+              options: {
+                ...normalizeStepOptions(inlineOptions),
+                issue: stepInputs.issue
+              }
+            });
+      } else if (second === "abandon") {
+        payload = await abandonSession({
+          targetRoot: cwd,
+          sessionId: first
+        });
+      } else if (second === "adopt-codex-thread") {
+        payload = await adoptCodexThreadId({
+          targetRoot: cwd,
+          sessionId: first,
+          codexThreadId: inlineOptions["codex-thread-id"] || inlineOptions.codexThreadId
+        });
+      } else if (!second) {
+        payload = await inspectSessionDetails({
+          targetRoot: cwd,
+          sessionId: first
+        });
+      } else {
+        payload = buildSessionErrorResponse({
+          targetRoot: cwd,
+          sessionId: first,
+          code: "unknown_session_subcommand",
+          message: `Unknown session subcommand: ${second}`,
+          repairCommand: `jskit session ${first}`
+        });
+      }
+
+      if (options.json) {
+        writeJson(stdout, payload);
+      } else {
+        writeSessionText(stdout, payload);
+      }
+      return payload.ok === false ? 1 : 0;
+    }
+  };
+}
+
+export { createSessionCommands };

package/src/server/core/argParser.js

@@ -143,7 +143,7 @@ function parseArgs(argv, { createCliError } = {}) {
       } else {
         const hasNextStringToken = typeof args[0] === "string";
         const nextToken = hasNextStringToken ? String(args[0]) : "";
-        if (hasNextStringToken && !nextToken.startsWith("-")) {
+        if (hasNextStringToken && (!nextToken.startsWith("-") || nextToken === "-")) {
           optionValueRaw = args.shift();
         }
       }
@@ -153,7 +153,7 @@ function parseArgs(argv, { createCliError } = {}) {
       }
       if (typeof optionValueRaw === "string") {
         const optionValue = optionValueRaw.trim();
-        if (!hasInlineValue && optionValue.startsWith("-")) {
+        if (!hasInlineValue && optionValue.startsWith("-") && optionValue !== "-") {
           throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
         }
         options.inlineOptions[optionName] = optionValue;

package/src/server/core/commandCatalog.js

@@ -198,6 +198,89 @@ 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, 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/worktrees/<session_id>.",
+      "The session id is timestamp-based and is the primary key.",
+      "Use --json for the stable machine-readable contract consumed by JSKIT AI Studio.",
+      "Use --issue - to read approved issue text 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 -"
+        ])
+      })
+    ]),
+    fullUse:
+      "jskit session [create|<sessionId>] [step|abandon|adopt-codex-thread] [--prompt <text>] [--issue <text>|--issue-file <path>] [--user-check <passed|failed>] [--codex-thread-id <id>] [--json]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandSession",
+    allowedFlagKeys: Object.freeze(["json"]),
+    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";