@kybernesis/create 0.23.3 → 0.24.0

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;
@@ -985,6 +992,17 @@ export async function upgrade(options = {}) {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "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",