@kybernesis/create 0.23.3 → 0.24.1

package/README.md

@@ -116,6 +116,12 @@ run and upgrade exits with status 2, prints that the gate can only run on the
 host, and gives the exact ssh command. It does not print "Do NOT deploy" because
 no eval exercised the code.
 
+`kyb upgrade --check` plans only: it prints what would change as one
+`KYB_UPGRADE_PLAN {"ok":true,"changes":[{"name","from","to"}],"resetsConversations":false}`
+line and installs, repairs and renews nothing. `@kybernesis/manage` reads it for
+the owner's Update card, and runs the real upgrade (with its eval gate, then a
+rebuild and a safe restart, or everything put back) from that card.
+
 Use `kyb upgrade --host` to run the gate over ssh after the upgrade. The target
 uses the same defaults as `kyb deploy`: `EVE_SSH_HOST`, then
 `$EXE_VM_NAME.exe.xyz`; `--host=<ssh-target>` overrides them. The remote project

package/dist/cli.js

@@ -84,7 +84,7 @@ const COMMANDS = {
     credential: "Write the agent credential onto a host (--local to stay here).",
     register: "Register this agent with the control plane (--name, --url).",
     deploy: "Deploy this agent to its host (--no-env to leave the env file alone).",
-    upgrade: "Bring @kybernesis packages and eve to certified versions (--host, --skip-eval, --allow-stale, --yes).",
+    upgrade: "Bring @kybernesis packages and eve to certified versions (--check, --host, --skip-eval, --allow-stale, --yes).",
     tui: "Talk to your agents in the terminal.",
     version: "Print the version of this tool.",
 };
@@ -116,6 +116,7 @@ function usage(command) {
       --host[=<target>]     ${dim("run the eval gate over ssh; defaults like kyb deploy")}
       --skip-eval           ${dim("skip the eval gate")}
       --allow-stale         ${dim("continue even when this kyb is behind the published version")}
+      --check               ${dim("print what would change (one KYB_UPGRADE_PLAN json line) and change nothing")}
       --yes, -y             ${dim("confirm an eve version change noninteractively")}
 `);
         }
@@ -179,6 +180,7 @@ switch (command) {
     case "upgrade":
         await upgrade({
             allowStale: rest.includes("--allow-stale"),
+            check: rest.includes("--check"),
             host: optionalValueFlag(rest, "host"),
             skipEval: rest.includes("--skip-eval"),
             yes: rest.includes("--yes") || rest.includes("-y"),

package/dist/upgrade.d.ts

@@ -29,6 +29,12 @@ export type GithubToolsMountRepair = {
 export declare function repairGithubToolsMount(cwd: string): GithubToolsMountRepair;
 export interface UpgradeOptions {
     allowStale?: boolean;
+    /**
+     * Plan only: print what an upgrade would change as one `KYB_UPGRADE_PLAN <json>`
+     * line and touch nothing (no install, no repair, no renewal of kyb itself).
+     * The owner's Update card reads it through @kybernesis/manage.
+     */
+    check?: boolean;
     host?: true | string;
     skipEval?: boolean;
     yes?: boolean;
@@ -40,5 +46,7 @@ type EvalGatePreflight = {
     reasons: string[];
 };
 export declare function preflightEvalGate(cwd: string): Promise<EvalGatePreflight>;
+/** The one line `kyb upgrade --check` prints for a program to read; everything else it prints is for people. */
+export declare const UPGRADE_PLAN_PREFIX = "KYB_UPGRADE_PLAN ";
 export declare function upgrade(options?: UpgradeOptions): Promise<void>;
 export {};

package/dist/upgrade.js

@@ -861,6 +861,11 @@ function startStoppedBridge(cwd, unit) {
         `  systemctl status ${unit}`);
     return false;
 }
+/** The one line `kyb upgrade --check` prints for a program to read; everything else it prints is for people. */
+export const UPGRADE_PLAN_PREFIX = "KYB_UPGRADE_PLAN ";
+function printPlan(plan) {
+    console.log(`${UPGRADE_PLAN_PREFIX}${JSON.stringify(plan)}`);
+}
 export async function upgrade(options = {}) {
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     const cwd = process.cwd();
@@ -871,7 +876,7 @@ export async function upgrade(options = {}) {
         ...(pkg.devDependencies ?? {}),
     };
     const selfVersion = checkSelfVersion();
-    if (selfVersion.kind === "stale" && !options.allowStale) {
+    if (selfVersion.kind === "stale" && !options.allowStale && !options.check) {
         /**
          * A stale kyb that is the PROJECT's own dependency renews itself.
          *
@@ -957,6 +962,8 @@ export async function upgrade(options = {}) {
         console.log(dim(`    note: eve@${eveLatest} exists upstream; ${EVE_VERSION} is the newest Kybernesis-certified version.`));
     }
     if (unresolved.size > 0) {
+        if (options.check)
+            printPlan({ ok: false, unresolved: [...unresolved].sort(), changes: [], resetsConversations: false });
         fail(`\nUpgrade planning failed for ${[...unresolved].sort().join(", ")}. ` +
             `No manifest, dependency tree, or service state was changed.`);
         return;
@@ -982,15 +989,39 @@ export async function upgrade(options = {}) {
         installedMajorMinor &&
         targetMajorMinor &&
         (installedMajorMinor[0] !== targetMajorMinor[0] || installedMajorMinor[1] !== targetMajorMinor[1]));
+    // eve already at the pin but saved as a range (an agent scaffolded before
+    // the pin was exact, or installed by hand): pin it in place. The version
+    // does not move, so this is not a change to plan or approve.
+    const loosePin = Boolean(eveTarget && eveInstalled === eveTarget && targets.some((target) => target.name === "eve" && target.currentRange !== eveTarget));
     const changed = [...new Set(targets
             .filter((target) => target.installedVersion !== target.targetVersion && !(target.name === "eve" && versionLt(target.targetVersion, target.installedVersion)))
             .map((target) => `${target.name}@${target.targetVersion}`))];
+    if (options.check) {
+        printPlan({
+            ok: true,
+            eve: { installed: eveInstalled ?? null, certified: EVE_VERSION },
+            changes: [...new Map(targets
+                    .filter((target) => changed.includes(`${target.name}@${target.targetVersion}`))
+                    .map((target) => [target.name, { name: target.name, from: target.installedVersion, to: target.targetVersion }])).values()],
+            resetsConversations: eveChanged,
+        });
+        return;
+    }
     if (eveChanged && !(await approveEveChange(cwd, options.yes === true, Boolean(deps["@kybernesis/buzz"])))) {
         process.exitCode = 1;
         return;
     }
     repairLocalQueueTimeouts(cwd, deps);
     if (changed.length === 0) {
+        if (loosePin) {
+            const pinned = commandResult("npm", ["install", "--save-exact", `eve@${eveTarget}`], cwd);
+            if (pinned.status !== 0) {
+                console.log(red(`\nCould not pin eve exactly to ${eveTarget}:\n${pinned.stderr.trim()}`));
+                process.exitCode = 1;
+                return;
+            }
+            console.log(`  ${green("✓")} eve pinned exactly to ${eveTarget} ${dim("(was a range)")}`);
+        }
         console.log(`\n${green("Everything is at latest certified versions.")}\n`);
         repairBuzzSetup(cwd, deps);
         repairRemovedDefaultTools(cwd);
@@ -1025,7 +1056,7 @@ export async function upgrade(options = {}) {
     }
     // Outside a clean install, eve goes in with --save-exact for the same
     // reason rewriteManifest pins it: npm would save a caret by default.
-    const eveChange = changed.find((spec) => spec.startsWith("eve@"));
+    const eveChange = changed.find((spec) => spec.startsWith("eve@")) ?? (loosePin ? `eve@${eveTarget}` : undefined);
     const others = changed.filter((spec) => spec !== eveChange);
     /**
      * A third-party extension whose declared peer range trails the certified

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.23.3",
+  "version": "0.24.1",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent \u2014 plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",