@kybernesis/create 0.8.1 → 0.8.2

package/dist/cli.js

@@ -60,7 +60,50 @@ function initOptions(rest) {
         yes: rest.includes('--yes') || rest.includes('-y'),
     };
 }
+/** What each command is for, in one line, as a person would ask for it. */
+const COMMANDS = {
+    init: "Scaffold a new agent: governed, remembering, multiplayer, self-testing.",
+    doctor: "Check this machine and this project before an engagement.",
+    arcana: "Set the memory workspaces and keys this agent uses.",
+    skills: "Install the FDE skill suite (--global for every project).",
+    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 the certified versions (--skip-eval).",
+    version: "Print the version of this tool.",
+};
+/**
+ * Print help instead of doing anything.
+ *
+ * Given a command, describe that command; otherwise list them. Either way this
+ * function's only effect is output — which is the entire point of it existing.
+ */
+function usage(command) {
+    if (command && COMMANDS[command]) {
+        console.log(`\n  ${bold(`kyb ${command}`)} — ${COMMANDS[command]}\n`);
+        return;
+    }
+    console.log(`\n  ${bold("kyb")} ${dim(VERSION)} — the Kybernesis agent CLI\n`);
+    for (const [name, description] of Object.entries(COMMANDS)) {
+        console.log(`  ${bold(name.padEnd(12))}${description}`);
+    }
+    console.log(`\n  ${dim("kyb <command> --help for one command.")}\n`);
+}
 const [, , command, ...rest] = process.argv;
+/**
+ * `--help` asks what a command does. It must never be the thing that does it.
+ *
+ * Checked before dispatch rather than inside each command, because "the flag
+ * was ignored" is not a failure anyone verifies per command — and the one time
+ * it mattered, `kyb upgrade --help` ran a real upgrade against a live agent's
+ * dependencies. Nothing broke, which is the wrong kind of luck: the same
+ * mistake on a command that writes credentials or deploys would not have been
+ * survivable.
+ */
+if (rest.includes("--help") || rest.includes("-h")) {
+    usage(command);
+    process.exit(0);
+}
 switch (command) {
     case "init":
         await init(rest.find((a) => !a.startsWith("-")), initOptions(rest));

package/dist/upgrade.js

@@ -1,14 +1,25 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { EVE_VERSION, bold, capture, dim, green, red, run, yellow } from "./util.js";
-const PACKAGES = [
-    "@kybernesis/arcana",
-    "@kybernesis/enterprise",
-    "@kybernesis/multiplayer",
-    "@kybernesis/engineer",
-    "@kybernesis/dispatch",
-    "@kybernesis/evals",
-];
+/**
+ * Which packages to upgrade: every `@kybernesis/*` this agent depends on.
+ *
+ * @remarks
+ * This was a fixed list of six, written when there were six. Four more shipped
+ * afterwards — connectors, local, manage and exe — and an agent using them was
+ * told "everything is at latest certified versions" while holding versions from
+ * months earlier. A hardcoded list does not fail loudly when it falls behind;
+ * it just quietly stops covering things, and the command that reports it is the
+ * same one that is wrong.
+ *
+ * Reading the manifest cannot fall behind. A package added tomorrow is covered
+ * by an upgrade run today.
+ */
+function kybernesisPackages(deps) {
+    return Object.keys(deps)
+        .filter((name) => name.startsWith("@kybernesis/"))
+        .sort();
+}
 function versionLt(a, b) {
     const pa = a.split(".").map(Number);
     const pb = b.split(".").map(Number);
@@ -52,13 +63,15 @@ export async function upgrade(skipEval) {
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
     const toUpgrade = [];
-    for (const name of PACKAGES) {
+    const unresolved = [];
+    for (const name of kybernesisPackages(deps)) {
         if (!deps[name])
             continue;
         const installed = capture("node", ["-p", `require('${name}/package.json').version`], cwd)?.trim();
         const latest = capture("npm", ["view", name, "version"])?.trim();
         if (!installed || !latest) {
             console.log(`  ${yellow("!")} ${name}: could not resolve versions`);
+            unresolved.push(name);
             continue;
         }
         if (installed === latest)
@@ -91,6 +104,16 @@ export async function upgrade(skipEval) {
             console.log(dim(`    note: eve@${eveLatest} exists upstream; ${EVE_VERSION} is the newest Kybernesis-certified version.`));
         }
     }
+    if (toUpgrade.length === 0 && unresolved.length > 0) {
+        // Saying everything is current, having just failed to check several
+        // packages, is the worst available answer: it is the sentence someone
+        // repeats to a client. Usually the dependencies are simply not installed
+        // here, which is worth naming rather than hiding behind a green tick.
+        console.log(`\n${yellow(`Checked what could be read. ${unresolved.length} package(s) could not be ` +
+            `resolved, so this is not a clean bill of health.`)}\n` +
+            `  ${dim("Usually: dependencies are not installed here. Run npm install, then kyb upgrade.")}\n`);
+        return;
+    }
     if (toUpgrade.length === 0) {
         console.log(`\n${green("Everything is at latest certified versions.")}\n`);
         return;

package/package.json

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