@jskit-ai/jskit-cli 0.2.79 → 0.2.81

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.79",
+  "version": "0.2.81",
   "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.80",
+    "@jskit-ai/kernel": "0.1.72",
+    "@jskit-ai/shell-web": "0.1.71"
   },
   "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,305 @@
+import { readFile } from "node:fs/promises";
+import {
+  abandonSession,
+  adoptCodexThreadId,
+  buildSessionErrorResponse,
+  createSession,
+  inspectSessionDiff,
+  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.gitStatus !== undefined && payload.unstagedDiff !== undefined) {
+    stdout.write("\nGit status:\n");
+    stdout.write(payload.gitStatus || "No changes.");
+    stdout.write("\n");
+    const diff = [payload.stagedDiff, payload.unstagedDiff, payload.untrackedDiff].filter(Boolean).join("\n");
+    if (diff) {
+      stdout.write("\nDiff:\n");
+      stdout.write(diff);
+      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 issueTitle = await resolveTextInput({
+    codePrefix: "issue_title",
+    fileOption: "issue-title-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --issue-title "<title>" --issue -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "issue-title"
+  });
+  if (issueTitle.ok === false) {
+    return issueTitle;
+  }
+
+  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;
+  }
+
+  const plan = await resolveTextInput({
+    codePrefix: "plan",
+    fileOption: "plan-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --plan -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "plan"
+  });
+  if (plan.ok === false) {
+    return plan;
+  }
+
+  return {
+    issue: issue.value,
+    issueTitle: issueTitle.value,
+    ok: true,
+    plan: plan.value
+  };
+}
+
+function normalizeStepOptions(inlineOptions = {}) {
+  return {
+    ...inlineOptions,
+    prompt: inlineOptions.prompt,
+    userCheck: inlineOptions["user-check"] || inlineOptions.userCheck
+  };
+}
+
+function resolveListArchiveOption(options = {}) {
+  const archives = [];
+  if (options.abandoned) {
+    archives.push("abandoned");
+  }
+  if (options.completed) {
+    archives.push("completed");
+  }
+  if (options.all) {
+    archives.push("all");
+  }
+  return archives.length > 0 ? archives : "active";
+}
+
+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,
+          archive: resolveListArchiveOption(options)
+        });
+      } 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,
+                issueTitle: stepInputs.issueTitle,
+                plan: stepInputs.plan
+              }
+            });
+      } else if (second === "abandon") {
+        payload = await abandonSession({
+          targetRoot: cwd,
+          sessionId: first
+        });
+      } else if (second === "diff") {
+        payload = await inspectSessionDiff({
+          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

@@ -23,6 +23,8 @@ function parseArgs(argv, { createCliError } = {}) {
         verbose: false,
         json: false,
         all: false,
+        abandoned: false,
+        completed: false,
         concrete: false,
         help: true,
         inlineOptions: {}
@@ -50,6 +52,8 @@ function parseArgs(argv, { createCliError } = {}) {
     verbose: false,
     json: false,
     all: false,
+    abandoned: false,
+    completed: false,
     concrete: false,
     help: false,
     inlineOptions: {}
@@ -109,6 +113,14 @@ function parseArgs(argv, { createCliError } = {}) {
       options.all = true;
       continue;
     }
+    if (token === "--abandoned") {
+      options.abandoned = true;
+      continue;
+    }
+    if (token === "--completed") {
+      options.completed = true;
+      continue;
+    }
     if (token === "--concrete") {
       options.concrete = true;
       continue;
@@ -143,7 +155,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 +165,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;