@jskit-ai/jskit-cli 0.2.78 → 0.2.80

package/package.json

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

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/cliRuntime/mutationWhen.js

@@ -52,6 +52,21 @@ function normalizeFileMutationRecord(value) {
   };
 }
 
+function normalizeDependencyMutationRecord(value) {
+  const record = ensureObject(value);
+  if (Object.keys(record).length < 1) {
+    return {
+      version: String(value || ""),
+      when: null
+    };
+  }
+
+  return {
+    version: String(record.version || record.value || "").trim(),
+    when: normalizeMutationWhen(record.when)
+  };
+}
+
 function normalizeMutationWhen(value) {
   const source = ensureObject(value);
   const allConditions = ensureArray(source.all)
@@ -304,6 +319,7 @@ function shouldApplyMutationWhen(
 export {
   normalizeMutationExtension,
   normalizeTemplateContextRecord,
+  normalizeDependencyMutationRecord,
   normalizeFileMutationRecord,
   normalizeMutationWhen,
   readObjectPath,

package/src/server/cliRuntime/packageInstallFlow.js

@@ -8,7 +8,9 @@ import {
   interpolateOptionValue
 } from "../shared/optionInterpolation.js";
 import {
-  normalizeFileMutationRecord
+  normalizeDependencyMutationRecord,
+  normalizeFileMutationRecord,
+  shouldApplyMutationWhen
 } from "./mutationWhen.js";
 import {
   applyViteMutations,
@@ -141,6 +143,13 @@ function resolveManagedSourceRecord(packageEntry, existingInstall = {}) {
   return sourceRecord;
 }
 
+function dependencyMutationUsesWhen(entries = []) {
+  return entries.some(([, rawDependencySpec]) => {
+    const dependencySpec = normalizeDependencyMutationRecord(rawDependencySpec);
+    return Boolean(dependencySpec.when);
+  });
+}
+
 async function applyPackagePositioning({
   packageEntry,
   packageOptions,
@@ -413,9 +422,28 @@ async function applyPackageInstall({
   const mutationDependencies = ensureObject(mutations.dependencies);
   const runtimeDependencies = ensureObject(mutationDependencies.runtime);
   const devDependencies = ensureObject(mutationDependencies.dev);
+  const runtimeDependencyEntries = Object.entries(runtimeDependencies);
+  const devDependencyEntries = Object.entries(devDependencies);
+  const needsDependencyWhenConfig = dependencyMutationUsesWhen([
+    ...runtimeDependencyEntries,
+    ...devDependencyEntries
+  ]);
+  const dependencyWhenConfigContext = needsDependencyWhenConfig
+    ? await loadMutationWhenConfigContext(appRoot)
+    : {};
   const mutationScripts = ensureObject(ensureObject(mutations.packageJson).scripts);
 
-  for (const [rawDependencyId, rawDependencyVersion] of Object.entries(runtimeDependencies)) {
+  for (const [rawDependencyId, rawDependencySpec] of runtimeDependencyEntries) {
+    const dependencySpec = normalizeDependencyMutationRecord(rawDependencySpec);
+    if (!shouldApplyMutationWhen(dependencySpec.when, {
+      options: packageOptions,
+      configContext: dependencyWhenConfigContext,
+      packageId: packageEntry.packageId,
+      mutationContext: `dependencies.runtime.${rawDependencyId}`
+    })) {
+      continue;
+    }
+
     const dependencyId = interpolateOptionValue(
       rawDependencyId,
       packageOptions,
@@ -423,7 +451,7 @@ async function applyPackageInstall({
       `dependencies.runtime.${rawDependencyId}.id`
     );
     const dependencyVersion = interpolateOptionValue(
-      String(rawDependencyVersion || ""),
+      dependencySpec.version,
       packageOptions,
       packageEntry.packageId,
       `dependencies.runtime.${rawDependencyId}.value`
@@ -447,7 +475,17 @@ async function applyPackageInstall({
     }
   }
 
-  for (const [rawDependencyId, rawDependencyVersion] of Object.entries(devDependencies)) {
+  for (const [rawDependencyId, rawDependencySpec] of devDependencyEntries) {
+    const dependencySpec = normalizeDependencyMutationRecord(rawDependencySpec);
+    if (!shouldApplyMutationWhen(dependencySpec.when, {
+      options: packageOptions,
+      configContext: dependencyWhenConfigContext,
+      packageId: packageEntry.packageId,
+      mutationContext: `dependencies.dev.${rawDependencyId}`
+    })) {
+      continue;
+    }
+
     const dependencyId = interpolateOptionValue(
       rawDependencyId,
       packageOptions,
@@ -455,7 +493,7 @@ async function applyPackageInstall({
       `dependencies.dev.${rawDependencyId}.id`
     );
     const dependencyVersion = interpolateOptionValue(
-      String(rawDependencyVersion || ""),
+      dependencySpec.version,
       packageOptions,
       packageEntry.packageId,
       `dependencies.dev.${rawDependencyId}.value`

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/commandHandlers/show/renderPackageText.js

@@ -2,6 +2,9 @@ import {
   ensureArray,
   ensureObject
 } from "../../shared/collectionUtils.js";
+import {
+  normalizeDependencyMutationRecord
+} from "../../cliRuntime/mutationWhen.js";
 import { createShowRenderHelpers } from "./renderHelpers.js";
 import { writePackageExportsSection } from "./renderPackageExports.js";
 import { writeCapabilitiesSections } from "./renderPackageCapabilities.js";
@@ -35,6 +38,12 @@ function resolveOwnershipGuidance(payload = {}) {
   return ensureObject(ensureObject(ensureObject(payload.metadata).jskit).ownershipGuidance);
 }
 
+function renderDependencyMutationSpec(versionSpec) {
+  const dependencySpec = normalizeDependencyMutationRecord(versionSpec);
+  const whenSuffix = dependencySpec.when ? ` when ${JSON.stringify(dependencySpec.when)}` : "";
+  return `${dependencySpec.version}${whenSuffix}`.trim();
+}
+
 function renderPackagePayloadText({
   payload,
   provides,
@@ -255,7 +264,7 @@ function renderPackagePayloadText({
       wrapWidth,
       items: runtimeMutationEntries.map(([dependencyId, versionSpec]) => {
         const dependencyText = String(dependencyId);
-        const versionText = String(versionSpec);
+        const versionText = renderDependencyMutationSpec(versionSpec);
         return {
           text: `${dependencyText} ${versionText}`,
           rendered: `${color.item(dependencyText)} ${color.installed(versionText)}`
@@ -325,7 +334,7 @@ function renderPackagePayloadText({
       wrapWidth,
       items: devMutationEntries.map(([dependencyId, versionSpec]) => {
         const dependencyText = String(dependencyId);
-        const versionText = String(versionSpec);
+        const versionText = renderDependencyMutationSpec(versionSpec);
         return {
           text: `${dependencyText} ${versionText}`,
           rendered: `${color.item(dependencyText)} ${color.installed(versionText)}`