@kybernesis/create 0.8.0 → 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/credential.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
 import { signIn } from "./register.js";
@@ -34,6 +35,19 @@ function envOf(dir) {
     }
     return out;
 }
+/**
+ * Is this machine the SSH target we were about to dial?
+ *
+ * Compared on the short name as well as the full one, because a host that
+ * answers to `box.example.xyz` usually reports itself as `box` — and the env
+ * file names whichever the person happened to type.
+ */
+function isThisHost(target) {
+    const self = hostname().toLowerCase();
+    const short = self.split(".")[0] ?? self;
+    const wanted = target.toLowerCase();
+    return wanted === self || wanted === short || wanted.split(".")[0] === short;
+}
 export async function credential(options) {
     const dir = options.dir ?? process.cwd();
     const env = envOf(dir);
@@ -85,9 +99,19 @@ export async function credential(options) {
     // leaves discovery silent, because `kyb deploy` deliberately never overwrites
     // a host .env.local that already exists.
     const target = options.host ?? env.EVE_SSH_HOST ?? (env.EXE_VM_NAME ? `${env.EXE_VM_NAME}.exe.xyz` : null);
-    if (options.local || !target) {
+    // Already ON the host it would otherwise SSH to.
+    //
+    // Naming a host is how a laptop installs the credential where the agent will
+    // read it. Run the same command on that host — the natural thing to do while
+    // setting one up over SSH — and it dialled itself, needed a key the host does
+    // not hold for itself, and failed at the last step of an otherwise complete
+    // sign-in. The file it wanted to write was already under the cursor.
+    const onTargetHost = target !== null && isThisHost(target);
+    if (options.local || !target || onTargetHost) {
         upsertEnv(dir, { KYBERNESIS_AGENT_CREDENTIAL: value });
         console.log(green("\n  ✓ credential written to ./.env.local"));
+        if (onTargetHost)
+            console.log(dim(`  This IS ${target}, so there was nothing to copy.`));
         if (!target)
             console.log(dim("  No host known — deploy it, or re-run with --host=<ssh target>."));
         return;

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);
@@ -20,19 +31,47 @@ function versionLt(a, b) {
     }
     return false;
 }
+/**
+ * Warn when this CLI is itself out of date.
+ *
+ * @remarks
+ * The certified eve version is a constant compiled INTO this tool, so an old
+ * kyb reports an old pin as though it were current — and does it with total
+ * confidence, in the one command whose entire job is telling you what current
+ * means. That failure runs the wrong way round: it tells a healthy agent it is
+ * ahead of certified and in "unsupported territory", which invites someone to
+ * downgrade a fleet that was fine.
+ *
+ * Checked here rather than at install because this is the command where being
+ * stale changes the answer.
+ */
+function warnIfStale() {
+    const installed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    const latest = capture("npm", ["view", "@kybernesis/create", "version"])?.trim();
+    if (!latest || latest === installed)
+        return;
+    if (!versionLt(installed, latest))
+        return;
+    console.log(`  ${yellow("!")} kyb ${installed} is behind ${latest}. The certified eve version is ` +
+        `compiled into this tool, so an old kyb reports an old pin as current.`);
+    console.log(`    ${dim("npm install -g @kybernesis/create@latest")}\n`);
+}
 export async function upgrade(skipEval) {
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     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)
@@ -65,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.0",
+  "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",
@@ -31,7 +31,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepare": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "node ../../scripts/prepublish.mjs"
   },

package/skills/kybernesis-packages/SKILL.md

@@ -82,9 +82,10 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   same shape as eve's `experimental_chatgpt()`), `hostPreflight()`, Photon
   iMessage credentials, and a `/preview` tool. Subpaths: `/slack`, `/photon`,
   `/sandbox`, `/preview`. See the `self-hosting` skill.
-- **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing,
-  engineer? })` = smoke + 5 memory + routing per dept + optional vision-loop
-  eval. Judge model ≠ model under test. Hermetic runs force all workspaces to
+- **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing, engineer?,
+  safety? })` = smoke + 5 memory + 1 safety (quoted content is data, on by
+  default) + routing per dept + optional engineer pair (vision loop, push-to-main
+  refusal). Judge model ≠ model under test. Hermetic runs force all workspaces to
   `<name>-eval` via the npm script.
 - **create** — the `kyb` CLI, and the whole lifecycle of an agent:
   `init` (scaffold; `--host=exe` also installs the hardened restart script),