@mycadet/cli 0.12.8 → 0.12.9

package/src/commands/completions.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { saveAssistantEntry } from "../lib/assistant-config.js";
+import { completeCadet } from "./completions.js";
+
+const COMMAND_NAMES = [
+  "backup",
+  "clean",
+  "client",
+  "completions",
+  "confirm",
+  "connect",
+  "hatch",
+  "ps",
+  "retire",
+  "sleep",
+  "use",
+  "wake",
+];
+
+describe("completeCadet", () => {
+  let lockfileDir: string;
+  let prevLockfileDir: string | undefined;
+
+  beforeEach(() => {
+    lockfileDir = mkdtempSync(join(tmpdir(), "cadet-completions-"));
+    prevLockfileDir = process.env.CADET_LOCKFILE_DIR;
+    process.env.CADET_LOCKFILE_DIR = lockfileDir;
+  });
+
+  afterEach(() => {
+    if (prevLockfileDir === undefined) delete process.env.CADET_LOCKFILE_DIR;
+    else process.env.CADET_LOCKFILE_DIR = prevLockfileDir;
+    rmSync(lockfileDir, { recursive: true, force: true });
+  });
+
+  function seed(id: string): void {
+    saveAssistantEntry({
+      assistantId: id,
+      cloud: "docker",
+      runtimeUrl: "http://localhost:7830",
+      hatchedAt: new Date().toISOString(),
+    });
+  }
+
+  test("no words yet offers every command name, sorted", () => {
+    const input: string[] = [];
+    expect(completeCadet(input, COMMAND_NAMES)).toEqual(
+      [...COMMAND_NAMES].sort(),
+    );
+    // The word under the cursor is popped from a COPY — the caller's array
+    // (bash's COMP_WORDS) must come back untouched.
+    expect(input).toEqual([]);
+  });
+
+  test("first positional of an assistant-name command offers known assistant names", () => {
+    seed("quill-owl-d4e5f6");
+    seed("fable-fox-a1b2c3");
+    // `cadet retire <TAB>` — the empty trailing word is the word being completed.
+    expect(completeCadet(["retire", ""], COMMAND_NAMES)).toEqual([
+      "fable-fox-a1b2c3",
+      "quill-owl-d4e5f6",
+    ]);
+  });
+
+  test("partial words are returned unfiltered — the shell does prefix filtering", () => {
+    seed("quill-owl-d4e5f6");
+    seed("fable-fox-a1b2c3");
+    expect(completeCadet(["retire", "fable"], COMMAND_NAMES)).toEqual([
+      "fable-fox-a1b2c3",
+      "quill-owl-d4e5f6",
+    ]);
+  });
+
+  test("flag prefixes fall through to the shell default (no candidates)", () => {
+    seed("fable-fox-a1b2c3");
+    expect(completeCadet(["retire", "--"], COMMAND_NAMES)).toEqual([]);
+    expect(completeCadet(["retire", "--name"], COMMAND_NAMES)).toEqual([]);
+  });
+
+  test("deeper positionals of an assistant-name command offer nothing", () => {
+    seed("fable-fox-a1b2c3");
+    expect(
+      completeCadet(["exec", "fable-fox-a1b2c3", ""], COMMAND_NAMES),
+    ).toEqual([]);
+    expect(
+      completeCadet(["logs", "fable-fox-a1b2c3", "tail", ""], COMMAND_NAMES),
+    ).toEqual([]);
+  });
+
+  test("commands that take no assistant name offer nothing after the command word", () => {
+    seed("fable-fox-a1b2c3");
+    expect(completeCadet(["hatch", ""], COMMAND_NAMES)).toEqual([]);
+    expect(completeCadet(["ps", ""], COMMAND_NAMES)).toEqual([]);
+  });
+
+  test("an unreadable/empty lockfile completes quietly with no names", () => {
+    // No entries seeded — the lockfile dir exists but has no lockfile.json.
+    expect(completeCadet(["retire", ""], COMMAND_NAMES)).toEqual([]);
+  });
+});

package/src/commands/completions.ts

@@ -0,0 +1,87 @@
+import { loadAllAssistants } from "../lib/assistant-config.js";
+
+/**
+ * Commands whose first positional argument is an assistant name — completing
+ * their first word offers the names of known assistants (from the lockfile)
+ * instead of falling through to shell file completion.
+ */
+const ASSISTANT_NAME_COMMANDS = new Set([
+  "exec",
+  "logs",
+  "message",
+  "restart",
+  "restore",
+  "retire",
+  "rollback",
+  "sleep",
+  "teleport",
+  "terminal",
+  "tunnel",
+  "unpair",
+  "upgrade",
+  "use",
+  "wake",
+]);
+
+/** Assistant names known to this CLI's lockfile; [] when the lockfile is unreadable. */
+function assistantNames(): string[] {
+  try {
+    return loadAllAssistants()
+      .map((entry) => entry.assistantId)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve completion candidates for the word the cursor is on.
+ *
+ * `words` carries every command-line word after `cadet` up to the cursor,
+ * INCLUDING the (possibly empty) word being completed — the same shape bash
+ * passes via `COMP_WORDS[@]:1`. The returned list is UNFILTERED: the shell
+ * (`compgen -W`) does the prefix filtering, so the CLI only decides WHAT
+ * KIND of thing completes here.
+ */
+export function completeCadet(
+  input: string[],
+  commandNames: readonly string[],
+): string[] {
+  const words = [...input];
+  const toComplete = words.pop() ?? "";
+  const preceding = words;
+
+  // Completing the command word itself (or nothing typed yet).
+  if (preceding.length === 0) {
+    return [...commandNames].sort();
+  }
+
+  // First positional of an assistant-name command: offer instance names.
+  // Flag prefixes fall through to shell default (no flag completion yet).
+  if (
+    preceding.length === 1 &&
+    ASSISTANT_NAME_COMMANDS.has(preceding[0]) &&
+    !toComplete.startsWith("-")
+  ) {
+    return assistantNames();
+  }
+
+  return [];
+}
+
+const BASH_COMPLETION_SCRIPT = `# bash completion for the cadet CLI — load with:  eval "$(cadet completions)"
+_cadet_completions() {
+  local candidates
+  candidates=$(cadet __complete "\${COMP_WORDS[@]:1}" 2>/dev/null)
+  COMPREPLY=($(compgen -W "$candidates" -- "\${COMP_WORDS[COMP_CWORD]}"))
+}
+complete -F _cadet_completions cadet`;
+
+// ── Entry point ─────────────────────────────────────────────────
+
+export const completions = Object.assign(
+  async function completions(): Promise<void> {
+    console.log(BASH_COMPLETION_SCRIPT);
+  },
+  { description: `Print bash completion setup (eval "$(cadet completions)")` },
+);

package/src/commands/exec.ts

@@ -75,28 +75,28 @@ export const exec = Object.assign(
     console.log("");
     console.log("Arguments:");
     console.log(
-      "  <name>              Name of the assistant (defaults to active)",
+      "  <name>              Name of the assistant, defaults to active",
     );
     console.log(
       "  <command...>        Command and arguments to run (after --)",
     );
     console.log("");
     console.log("Options:");
-    console.log("  --service <svc>     Target service (default: assistant)");
+    console.log("  --service <svc>     Target service, defaults to assistant");
     console.log(
       "  -it                 Interactive mode with TTY (like docker exec -it)",
     );
     console.log(
-      "  --timeout <secs>    Timeout in seconds (default: 30, 0 = no timeout)",
+      "  --timeout <secs>    Timeout in seconds — default 30, 0 = no timeout",
     );
     console.log(
-      "  --verbose           Show debug output (SSE events, sentinel parsing)",
+      "  --verbose           Show debug output",
     );
     console.log("");
     console.log("Services:");
-    console.log("  assistant (or mycadet)");
-    console.log("  gateway (or cadet-gateway)");
-    console.log("  credential-executor (or cadet-credential-executor)");
+    console.log("  assistant");
+    console.log("  gateway");
+    console.log("  credential-executor");
     console.log("");
     console.log("Examples:");
     console.log("  cadet exec -- ls -la /workspace");

package/src/commands/flags.ts

@@ -59,7 +59,7 @@ function printFlagTable(flags: FeatureFlagEntry[]): void {
     console.log(formatRow(row));
   }
   console.log("");
-  console.log("* = overridden (differs from default)");
+  console.log("* = overridden");
 }
 
 function printHelp(): void {
@@ -67,7 +67,7 @@ function printHelp(): void {
   console.log("");
   console.log("Show and toggle feature flags for the active assistant.");
   console.log(
-    "Reads from the gateway's merged flag state (persisted overrides > remote > defaults).",
+    "Reads from the gateway's merged flag state.",
   );
   console.log("");
   console.log("Subcommands:");

package/src/commands/hatch.ts

@@ -76,7 +76,7 @@ function parseArgs(): HatchArgs {
         "  --watch                   Run assistant and gateway in watch mode (hot reload on source changes)",
       );
       console.log(
-        "  --source <path>           Build images from a local source tree at <path> (no watcher). Useful for callers (e.g. evals) that want each run to pick up local CLI changes.",
+        "  --source <path>           Build images from a local source tree at <path>. Useful for callers that want each run to pick up local CLI changes.",
       );
       console.log(
         "  --keep-alive              Stay alive after hatch, exit when gateway stops",

package/src/commands/logs.ts

@@ -32,19 +32,19 @@ function printHelp(): void {
   console.log("");
   console.log("Arguments:");
   console.log(
-    "  <name>                Name of the assistant (defaults to latest)",
+    "  <name>                Name of the assistant, defaults to latest",
   );
   console.log("");
   console.log("Options:");
-  console.log("  -f, --follow          Follow log output (stream new lines)");
-  console.log("  -n, --tail <N>        Show last N lines (default: all)");
+  console.log("  -f, --follow          Follow log output");
+  console.log("  -n, --tail <N>        Show last N lines");
   console.log("  -t, --timestamps      Show timestamps on each line");
   console.log(
-    "  --since <time>        Show logs since timestamp or relative (e.g. 10m, 2h)",
+    "  --since <time>        Show logs since timestamp or relative, e.g. 10m or 2h",
   );
   console.log("  --until <time>        Show logs until timestamp or relative");
   console.log(
-    "  -s, --service <name>  Filter to a specific service (e.g. assistant, gateway)",
+    "  -s, --service <name>  Filter to a specific service",
   );
   console.log("  -h, --help            Show this help");
 }
@@ -186,13 +186,13 @@ async function showLocalLogs(
 
   if (opts.since && !sinceDate) {
     console.error(
-      `Error: Could not parse --since value '${opts.since}'. Use relative (e.g. 10m, 2h) or ISO format.`,
+      `Error: Could not parse --since value '${opts.since}'. Use a relative value such as 10m or 2h, or ISO format.`,
     );
     process.exit(1);
   }
   if (opts.until && !untilDate) {
     console.error(
-      `Error: Could not parse --until value '${opts.until}'. Use relative (e.g. 10m, 2h) or ISO format.`,
+      `Error: Could not parse --until value '${opts.until}'. Use a relative value such as 10m or 2h, or ISO format.`,
     );
     process.exit(1);
   }

package/src/commands/ps.ts

@@ -64,8 +64,54 @@ interface ColWidths {
   info: number;
 }
 
+/**
+ * Terminal display width for table alignment: emoji render two cells wide
+ * (including ZWJ sequences like 🧑‍🚀 and VS16 pairs like ⚠️), while the ZWJ
+ * and variation selectors themselves render zero. `.length` counts UTF-16
+ * units and none of that, which is what broke the STATUS and INFO columns
+ * whenever an emoji appeared in an earlier one.
+ */
+export function displayWidth(s: string): number {
+  const chars = [...s];
+  let width = 0;
+  // A ZWJ joins the previous and next glyphs into ONE grapheme (🧑‍🚀 renders
+  // as a single 2-cell astronaut), so the glyph after a ZWJ adds no width.
+  let joinedByZwj = false;
+  for (let i = 0; i < chars.length; i++) {
+    const cp = chars[i]?.codePointAt(0) ?? 0;
+    // Zero-width: the joiner, the variation selectors, skin-tone modifiers.
+    if (cp === 0x200d) {
+      joinedByZwj = true;
+      continue;
+    }
+    if (cp === 0xfe0e || cp === 0xfe0f) continue;
+    if (cp >= 0x1f3fb && cp <= 0x1f3ff) continue;
+    const next = chars[i + 1]?.codePointAt(0);
+    if (!joinedByZwj) {
+      // A VS16 after a narrow symbol forces emoji presentation — two cells.
+      width += isWideCodePoint(cp) || next === 0xfe0f ? 2 : 1;
+    }
+    joinedByZwj = false;
+  }
+  return width;
+}
+
+function isWideCodePoint(cp: number): boolean {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals and punctuation
+    (cp >= 0x3040 && cp <= 0x318f) || // Hiragana, Katakana, bopomofo
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+    (cp >= 0xfe30 && cp <= 0xfe6f) || // CJK compatibility forms
+    (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    cp >= 0x1f000 // emoji and symbol blocks (🟢, 🚀, 🧑, …)
+  );
+}
+
 function pad(s: string, w: number): string {
-  return s + " ".repeat(Math.max(0, w - s.length));
+  return s + " ".repeat(Math.max(0, w - displayWidth(s)));
 }
 
 function computeColWidths(
@@ -79,14 +125,17 @@ function computeColWidths(
 ): ColWidths {
   const all = [headers, ...rows];
   return {
-    name: Math.max(...all.map((r) => r.name.length)),
-    type: Math.max(...all.map((r) => r.type.length)),
-    status: Math.max(...all.map((r) => r.status.length), "checking...".length),
-    info: Math.max(...all.map((r) => r.info.length)),
+    name: Math.max(...all.map((r) => displayWidth(r.name))),
+    type: Math.max(...all.map((r) => displayWidth(r.type))),
+    status: Math.max(
+      ...all.map((r) => displayWidth(r.status)),
+      "checking...".length,
+    ),
+    info: Math.max(...all.map((r) => displayWidth(r.info))),
   };
 }
 
-function formatRow(r: TableRow, colWidths: ColWidths): string {
+export function formatRow(r: TableRow, colWidths: ColWidths): string {
   return `  ${pad(r.name, colWidths.name)}  ${pad(r.type, colWidths.type)}  ${pad(r.status, colWidths.status)}  ${r.info}`;
 }
 
@@ -459,7 +508,7 @@ async function getAssistantProcessRows(
 ): Promise<TableRow[]> {
   const cloud = entry.cloud;
 
-  console.log(`Processes for ${formatAssistantReference(entry)} (${cloud}):`);
+  console.log(`Processes for ${formatAssistantReference(entry)} — ${cloud}:`);
   console.log(`Location: ${locationFor(entry)}\n`);
 
   if (cloud === "local") {
@@ -830,5 +879,5 @@ export const ps = Object.assign(
     }
     printTable(rows);
   },
-  { description: "List assistants (or processes for a specific assistant)" },
+  { description: "List assistants" },
 );

package/src/commands/restore.ts

@@ -474,7 +474,7 @@ async function restorePlatform(
           }
         }
         // Transient error (5xx, network) — retry
-        console.warn(`Polling failed, retrying... (${msg})`);
+        console.warn(`Polling failed: ${msg}. Retrying...`);
         continue;
       }
 
@@ -680,7 +680,7 @@ export const restore = Object.assign(
   }
 
   const sizeMB = formatBundleSizeMb(bundleFileSizeBytes(fromPath));
-  console.log(`Reading ${fromPath} (${sizeMB} MB)...`);
+  console.log(`Reading ${fromPath} — ${sizeMB} MB...`);
 
   // Detect topology and route platform assistants through Django import
   const cloud =

package/src/commands/retire.ts

@@ -287,12 +287,12 @@ async function retireInner(): Promise<void> {
     console.log("");
     console.log("Delete an assistant instance and archive its data.");
     console.log(
-      "With no name or ID, retires the active assistant (see `cadet use`). By default, retire prints the assistant name, ID, cloud, and runtime before asking for confirmation.",
+      "With no name or ID, retires the active assistant — see `cadet use`. By default, retire prints the assistant name, ID, cloud, and runtime before asking for confirmation.",
     );
     console.log("");
     console.log("Arguments:");
     console.log(
-      "  <name-or-id>         Assistant display name or ID to retire (defaults to the active assistant)",
+      "  <name-or-id>         Assistant display name or ID to retire, defaults to the active assistant",
     );
     console.log("");
     console.log("Options:");

package/src/commands/rollback.ts

@@ -51,12 +51,12 @@ function parseArgs(): { name: string | null; version: string | null } {
       console.log("");
       console.log("Arguments:");
       console.log(
-        "  <name>               Name of the assistant (default: active or only assistant)",
+        "  <name>               Name of the assistant, defaults to active or only assistant",
       );
       console.log("");
       console.log("Options:");
       console.log(
-        "  --version <version>  Target version (optional for managed — omit to roll back to previous)",
+        "  --version <version>  Target version, optional for managed — omit to roll back to previous",
       );
       console.log("");
       console.log("Examples:");

package/src/commands/sleep.ts

@@ -71,7 +71,7 @@ export const sleep = Object.assign(
     console.log("");
     console.log("Arguments:");
     console.log(
-      "  <name>    Name of the assistant to stop (default: active or only local)",
+      "  <name>    Name of the assistant to stop, defaults to active or only local",
     );
     console.log("");
     console.log("Options:");
@@ -88,7 +88,7 @@ export const sleep = Object.assign(
       "            schedules) to finish before stopping. Waits as long as it",
     );
     console.log(
-      "            takes by default; pass a duration (e.g. --wait 90s, --wait 10m)",
+      "            takes by default; pass a duration, e.g. --wait 90s or --wait 10m",
     );
     console.log(
       "            to bound the wait. Ctrl-C cancels and leaves the assistant running.",

package/src/commands/teleport.ts

@@ -100,7 +100,7 @@ function printHelp(): void {
   console.log(
     "The source and target must be different environments. Same-environment",
   );
-  console.log("transfers (e.g. local to local) are not supported.");
+  console.log("transfers such as local to local are not supported.");
   console.log("");
   console.log(
     "Before exporting, the source assistant is backed up. Platform sources",
@@ -159,7 +159,7 @@ function printHelp(): void {
     "      Import data from my-local into existing docker assistant my-docker",
   );
   console.log(
-    "      (or hatch a new docker assistant named my-docker if it doesn't exist)",
+    "      or hatch a new docker assistant named my-docker if it doesn't exist",
   );
   console.log("");
   console.log("  cadet teleport --from my-local --platform");
@@ -415,7 +415,7 @@ async function backupSourceBeforeTeleport(
   cloud: string,
   displayName: string,
 ): Promise<void> {
-  console.log(`Backing up ${displayName} (${cloud})...`);
+  console.log(`Backing up ${displayName} on ${cloud}...`);
   try {
     if (isCloudHome(cloud)) {
       const cloudToken = readCloudToken();
@@ -443,7 +443,7 @@ async function backupSourceBeforeTeleport(
       timeoutMs: LOCAL_SOURCE_BACKUP_TIMEOUT_MS,
     });
     if (!backupPath) {
-      throw new Error("backup export failed (see warning above)");
+      throw new Error("backup export failed — see the warning above");
     }
     pruneOldBackups(entry.assistantId, 3, "pre-teleport");
     console.log(`Backup saved: ${backupPath}`);
@@ -470,7 +470,7 @@ async function exportFromAssistant(
   const cloudToken = readCloudToken();
   if (!cloudToken) {
     console.error(
-      "Not logged in. Run 'cadet login' first (required for GCS-based teleport).",
+      "Not logged in. Run 'cadet login' first.",
     );
     process.exit(1);
   }
@@ -688,7 +688,7 @@ async function importToAssistant(
   const cloudToken = readCloudToken();
   if (!cloudToken) {
     console.error(
-      "Not logged in. Run 'cadet login' first (required for GCS-based teleport).",
+      "Not logged in. Run 'cadet login' first.",
     );
     process.exit(1);
   }
@@ -990,7 +990,7 @@ export async function resolveOrHatchTarget(
         );
         process.exit(1);
       }
-      console.log(`Target: ${targetName} (${targetEnv})`);
+      console.log(`Target: ${targetName} — ${targetEnv}`);
       return existing;
     }
 
@@ -1204,7 +1204,7 @@ async function tryInjectCloudCredentials(
 ): Promise<void> {
   const token = readCloudToken();
   if (!token) {
-    console.log("  Skipped cloud credential injection (not logged in).");
+    console.log("  Skipped cloud credential injection — not logged in.");
     return;
   }
 
@@ -1393,13 +1393,13 @@ export const teleport = Object.assign(
             ? fromEntry.runtimeUrl
             : undefined;
 
-      console.log(`Exporting from ${from} (${fromCloud})...`);
+      console.log(`Exporting from ${from} on ${fromCloud}...`);
       const { bundleKey } = await exportFromAssistant(
         fromEntry,
         fromCloud,
         bundleCloudUrl,
       );
-      console.log(`Importing to ${existingTarget.assistantId} (${toCloud})...`);
+      console.log(`Importing to ${existingTarget.assistantId} on ${toCloud}...`);
       await importToAssistant(
         existingTarget,
         toCloud,
@@ -1410,7 +1410,7 @@ export const teleport = Object.assign(
     } else {
       // No existing target — just describe what would happen
       console.log("Dry run summary:");
-      console.log(`  Would export data from: ${from} (${fromCloud})`);
+      console.log(`  Would export data from: ${from} on ${fromCloud}`);
       console.log(`  Would upload bundle via signed URL`);
       console.log(
         `  Would hatch a new ${targetEnv} assistant${targetName ? ` named '${targetName}'` : ""}`,
@@ -1482,7 +1482,7 @@ export const teleport = Object.assign(
     // resolveOrHatchTarget writes to the new entry).
     await backupSourceBeforeTeleport(fromEntry, fromCloud, from);
 
-    console.log(`Exporting from ${from} (${fromCloud})...`);
+    console.log(`Exporting from ${from} on ${fromCloud}...`);
     const bundleCloudUrl = targetCloudUrl ?? getCloudUrl();
     const { bundleKey } = await exportFromAssistant(
       fromEntry,
@@ -1495,7 +1495,7 @@ export const teleport = Object.assign(
     const toCloud = toEntry.cloud;
 
     // Import from GCS
-    console.log(`Importing to ${toEntry.assistantId} (${toCloud})...`);
+    console.log(`Importing to ${toEntry.assistantId} on ${toCloud}...`);
     await importToAssistant(
       toEntry,
       toCloud,
@@ -1555,7 +1555,7 @@ export const teleport = Object.assign(
   await backupSourceBeforeTeleport(fromEntry, fromCloud, from);
 
   // Export from source (bundle lives in GCS after this returns).
-  console.log(`Exporting from ${from} (${fromCloud})...`);
+  console.log(`Exporting from ${from} on ${fromCloud}...`);
   const { bundleKey } = await exportFromAssistant(
     fromEntry,
     fromCloud,
@@ -1632,7 +1632,7 @@ export const teleport = Object.assign(
   }
 
   // Import to target (also GCS-driven)
-  console.log(`Importing to ${toEntry.assistantId} (${toCloud})...`);
+  console.log(`Importing to ${toEntry.assistantId} on ${toCloud}...`);
   await importToAssistant(
     toEntry,
     toCloud,
@@ -1660,7 +1660,7 @@ export const teleport = Object.assign(
       removeAssistantEntry(fromEntry.assistantId);
       console.log(`Source assistant '${from}' retired.`);
     } else {
-      console.log(`Source assistant '${from}' kept (--keep-source).`);
+      console.log(`Source assistant '${from}' kept via --keep-source.`);
     }
   }
 

package/src/commands/terminal.ts

@@ -71,7 +71,7 @@ function printHelp(): void {
   console.log("");
   console.log("Options:");
   console.log(
-    "  <name>              Name of the assistant (defaults to active)",
+    "  <name>              Name of the assistant, defaults to active",
   );
   console.log(
     "  --assistant <name>  Explicit assistant name (alternative to positional)",