@lizard-build/cli 4.0.42 → 4.0.43

package/src/index.ts

@@ -6,6 +6,7 @@ import { setJSONMode, isJSONMode, error } from "./lib/format.js";
 import { requireAuth, isLoggedIn } from "./lib/auth.js";
 import { setBaseURL, setAccessToken, APIError, isProjectDeletedError, isAccountScopeError } from "./lib/api.js";
 import { checkForUpdateInBackground, runBackgroundUpdate, CURRENT_VERSION } from "./lib/updater.js";
+import { skillFor } from "./lib/skill-route.js";
 
 const BANNER = chalk.rgb(16, 185, 129)(
   [
@@ -27,34 +28,34 @@ const BANNER = chalk.rgb(16, 185, 129)(
 // of guessing commands from flag docs alone.
 const AGENTS_HELP = [
   chalk.bold("Start here (for AI agents):"),
-  "  " + chalk.cyan("lizard skills get core"),
+  "  " + chalk.cyan("lizard skills get sandbox") + chalk.dim("   sandboxes: run code, files, ports, snapshots, desktop, agents"),
+  "  " + chalk.cyan("lizard skills get core") + chalk.dim("      deploys: services, databases, builds, secrets, domains"),
   "",
   chalk.dim(
-    "  Skills ship with the CLI (always version-matched) and cover the full app",
+    "  Skills ship with the CLI (always version-matched) and come with copy-paste",
   ),
   chalk.dim(
-    "  lifecycle — deploy, link, addons, logs, scaling, secrets, domains — with",
-  ),
-  chalk.dim(
-    "  copy-paste examples. Prefer this over guessing commands from flag docs alone.",
+    "  examples. Prefer them over guessing commands from flag docs alone.",
   ),
 ].join("\n");
 
+
 // Compact form of the same pointer, shown on every subcommand's `--help` so the
 // per-command flag docs never read as the whole story. Mirrors the `agents`
 // block that `--help --json` already emits for every command; one tight line so
 // it sits above a subcommand's Usage without crowding it.
-const AGENTS_HELP_COMPACT =
+const agentsHelpCompact = (skill: string) =>
   chalk.bold("For AI agents:") +
   " run " +
-  chalk.cyan("lizard skills get core") +
+  chalk.cyan(`lizard skills get ${skill}`) +
   chalk.dim(" for version-matched usage and examples.");
 
-/** Attach the compact agents pointer to every (nested) subcommand's help. */
-function addAgentsPointerToSubcommands(cmd: Command) {
+/** Attach the compact agents pointer to every (nested) subcommand's help, naming the skill for its subtree. */
+function addAgentsPointerToSubcommands(cmd: Command, skill?: string) {
   for (const sub of cmd.commands) {
-    sub.addHelpText("before", AGENTS_HELP_COMPACT + "\n");
-    addAgentsPointerToSubcommands(sub);
+    const own = skill ?? skillFor(sub.name());
+    sub.addHelpText("before", agentsHelpCompact(own) + "\n");
+    addAgentsPointerToSubcommands(sub, own);
   }
 }
 
@@ -274,6 +275,13 @@ function findTargetCommand(
   return { target: cur, unknown: null };
 }
 
+/** The command directly under the root that `cmd` belongs to. */
+function topLevelOf(cmd: Command): Command {
+  let top = cmd;
+  while (top.parent && top.parent !== program) top = top.parent;
+  return top;
+}
+
 function dumpOption(o: any) {
   return {
     flags: o.flags,
@@ -386,8 +394,9 @@ async function main() {
       cli: "lizard",
       version: CURRENT_VERSION,
       agents: {
-        start: "lizard skills get core",
-        note: "Skills ship with this CLI version and cover the full app lifecycle (deploy, link, addons, logs, scaling, secrets, domains) with copy-paste examples. Prefer this over guessing commands from flag docs alone.",
+        start: `lizard skills get ${isRoot ? "core" : skillFor(topLevelOf(target).name())}`,
+        skills: { sandbox: "lizard skills get sandbox", core: "lizard skills get core" },
+        note: "Skills ship with this CLI version, with copy-paste examples: `sandbox` for sandboxes (run code, files, ports, snapshots, desktop, coding agents), `core` for deploys (services, databases, builds, secrets, domains). Prefer them over guessing commands from flag docs alone.",
       },
       command: dumpCommand(target),
       globalOptions: isRoot

package/src/lib/skill-route.ts

@@ -0,0 +1,7 @@
+/** Top-level commands whose work the `sandbox` skill covers; everything else is in `core` (deploys). */
+const SANDBOX_COMMANDS = new Set(["sandbox", "volume", "agents"]);
+
+/** Which embedded skill an agent should read for a top-level command. */
+export function skillFor(topLevel: string): "sandbox" | "core" {
+  return SANDBOX_COMMANDS.has(topLevel) ? "sandbox" : "core";
+}

package/src/lib/updater.ts

@@ -5,7 +5,7 @@ import { join, dirname } from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
 
-export const CURRENT_VERSION = "4.0.42";
+export const CURRENT_VERSION = "4.0.43";
 const RELEASES_API = "https://api.github.com/repos/lizard-build/lizard-cli/releases/latest";
 const RELEASE_BASE = "https://github.com/lizard-build/lizard-cli/releases/latest/download";
 

package/test/unit/skills.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test, afterEach } from "vitest";
+import * as path from "node:path";
+import { EMBEDDED_SKILLS } from "../../src/lib/skills-data.generated.js";
+import { expandIncludes } from "../../src/commands/skill.js";
+import { skillFor } from "../../src/lib/skill-route.js";
+import * as fs from "node:fs";
+
+const SKILL_DATA = path.resolve(import.meta.dirname, "../../skill-data");
+
+function frontmatter(md: string): Record<string, string> {
+  const block = md.slice(4, md.indexOf("\n---", 3));
+  return Object.fromEntries(
+    block.split("\n").map((l) => l.match(/^([\w-]+):\s*"?(.*?)"?$/)).filter(Boolean).map((m) => [m![1], m![2]]),
+  );
+}
+
+/** GitHub-style heading slug, which the skills' own links use. */
+const slug = (h: string) => h.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
+
+describe("embedded skills", () => {
+  test("ship core and sandbox, and not the shared parts as a skill", () => {
+    expect(Object.keys(EMBEDDED_SKILLS).sort()).toEqual(["core", "sandbox"]);
+  });
+
+  test.each(["core", "sandbox"])("%s has the shared basics inlined", (name) => {
+    const md = EMBEDDED_SKILLS[name].content;
+    expect(md).not.toContain("<!-- include");
+    for (const h of ["## Execution rules", "## Discovery", "## Sign-in", "## Exit codes", "## Default project", "## Billing"]) {
+      expect(md).toContain(`\n${h}\n`);
+    }
+  });
+
+  test.each(["core", "sandbox"])("%s: every #link points at a heading in the same skill", (name) => {
+    const md = EMBEDDED_SKILLS[name].content;
+    const headings = new Set([...md.matchAll(/^#{2,3} (.+)$/gm)].map((m) => slug(m[1])));
+    const links = [...md.matchAll(/\]\(#([\w-]+)\)/g)].map((m) => m[1]);
+    expect(links.filter((l) => !headings.has(l))).toEqual([]);
+  });
+
+  test("descriptions fit the 1024-character limit and say who they are for", () => {
+    const core = frontmatter(EMBEDDED_SKILLS.core.content);
+    const sandbox = frontmatter(EMBEDDED_SKILLS.sandbox.content);
+    expect(sandbox.name).toBe("lizard-sandbox");
+    expect(core.description.length).toBeLessThanOrEqual(1024);
+    expect(sandbox.description.length).toBeLessThanOrEqual(1024);
+    expect(sandbox.description).toMatch(/^Creates and manages Lizard sandboxes/);
+  });
+
+  test("sandbox work lives only in the sandbox skill, and core points there", () => {
+    const core = EMBEDDED_SKILLS.core.content;
+    const sandbox = EMBEDDED_SKILLS.sandbox.content;
+    expect(core).not.toMatch(/^## Sandboxes/m);
+    expect(core).toContain("lizard skills get sandbox --json");
+    for (const h of ["## Quickstart", "## Templates", "## Lifetime", "## Snapshots and pause/resume", "## From code: Lizard SDK"]) {
+      expect(sandbox).toContain(`\n${h}\n`);
+    }
+    expect(sandbox).toContain("lizard skills get core --json");
+  });
+});
+
+describe("skill routing in --help", () => {
+  test("sandbox, volume and agents point at the sandbox skill, the rest at core", () => {
+    expect(["sandbox", "volume", "agents"].map(skillFor)).toEqual(["sandbox", "sandbox", "sandbox"]);
+    expect(["up", "logs", "secrets", "add"].map(skillFor)).toEqual(["core", "core", "core", "core"]);
+  });
+});
+
+describe("LIZARD_SKILLS_DIR (authoring from files)", () => {
+  test("includes expand the same way as the embedded copy", () => {
+    const raw = fs.readFileSync(path.join(SKILL_DATA, "sandbox", "SKILL.md"), "utf8");
+    expect(expandIncludes(raw, SKILL_DATA)).toBe(EMBEDDED_SKILLS.sandbox.content);
+  });
+
+  test("an include outside the skills folder is left as it is", () => {
+    const line = "<!-- include: ../package.json -->";
+    expect(expandIncludes(line, SKILL_DATA)).toBe(line);
+  });
+});