@lizard-build/cli 4.0.44 → 4.0.45

package/src/commands/skill.ts

@@ -11,11 +11,16 @@ import { EMBEDDED_SKILLS } from "../lib/skills-data.generated.js";
 //
 // LIZARD_SKILLS_DIR overrides the embedded source with a real directory — useful
 // for authoring new skills locally without a rebuild.
+//
+// A skill is SKILL.md plus optional references/<ref>.md files that go deeper on
+// one part of the platform; `lizard skills get <name> --ref <ref>` prints one.
 
 interface Source {
   list(): string[];
   read(name: string): string | null;
-  pathOf(name?: string): string;
+  refs(name: string): string[];
+  readRef(name: string, ref: string): string | null;
+  pathOf(name?: string, ref?: string): string;
 }
 
 function fsSource(dir: string): Source {
@@ -42,7 +47,29 @@ function fsSource(dir: string): Source {
         return null;
       }
     },
-    pathOf: (name) => (name ? path.join(dir, name, "SKILL.md") : dir),
+    refs: (name) => {
+      try {
+        return readdirSync(path.join(dir, name, "references"))
+          .filter((f) => f.endsWith(".md"))
+          .map((f) => f.slice(0, -3))
+          .sort();
+      } catch {
+        return [];
+      }
+    },
+    readRef: (name, ref) => {
+      try {
+        return readFileSync(path.join(dir, name, "references", `${ref}.md`), "utf8");
+      } catch {
+        return null;
+      }
+    },
+    pathOf: (name, ref) => {
+      if (!name) return dir;
+      return ref
+        ? path.join(dir, name, "references", `${ref}.md`)
+        : path.join(dir, name, "SKILL.md");
+    },
   };
 }
 
@@ -50,8 +77,14 @@ function embeddedSource(): Source {
   return {
     list: () => Object.keys(EMBEDDED_SKILLS).sort(),
     read: (name) => EMBEDDED_SKILLS[name]?.content ?? null,
-    pathOf: (name) =>
-      name ? `embedded://skills/${name}/SKILL.md` : "embedded://skills",
+    refs: (name) => Object.keys(EMBEDDED_SKILLS[name]?.references ?? {}).sort(),
+    readRef: (name, ref) => EMBEDDED_SKILLS[name]?.references[ref] ?? null,
+    pathOf: (name, ref) => {
+      if (!name) return "embedded://skills";
+      return ref
+        ? `embedded://skills/${name}/references/${ref}.md`
+        : `embedded://skills/${name}/SKILL.md`;
+    },
   };
 }
 
@@ -97,6 +130,29 @@ function readSkill(
   return { md, meta: parseFrontmatter(md) };
 }
 
+function readRef(src: Source, name: string, ref: string): string {
+  readSkill(src, name);
+  const md = src.readRef(name, ref);
+  if (md == null) {
+    const refs = src.refs(name);
+    throw new Error(
+      `Reference '${ref}' not found in skill '${name}'. ` +
+        (refs.length
+          ? `Available: ${refs.join(", ")}.`
+          : `This skill has no references.`),
+    );
+  }
+  return md;
+}
+
+function refEntries(src: Source, name: string) {
+  return src.refs(name).map((ref) => ({
+    name: ref,
+    path: src.pathOf(name, ref),
+    command: `lizard skills get ${name} --ref ${ref}`,
+  }));
+}
+
 function shortDesc(desc: string, max = 100): string {
   const oneLine = desc.replace(/\s+/g, " ").trim();
   return oneLine.length > max ? oneLine.slice(0, max - 1) + "…" : oneLine;
@@ -118,12 +174,13 @@ export function registerSkill(program: Command) {
         printJSON({
           dir: src.pathOf(),
           skills: names.map((n) => {
+            let description = "";
             try {
-              const { meta } = readSkill(src, n);
-              return { name: n, description: meta.description || "" };
+              description = readSkill(src, n).meta.description || "";
             } catch {
-              return { name: n, description: "" };
+              // unreadable SKILL.md: list it without a description
             }
+            return { name: n, description, references: src.refs(n) };
           }),
         });
         return;
@@ -133,38 +190,54 @@ export function registerSkill(program: Command) {
         return;
       }
       const rows = names.map((n) => {
+        let description = "";
         try {
-          const { meta } = readSkill(src, n);
-          return [n, shortDesc(meta.description || "")];
+          description = shortDesc(readSkill(src, n).meta.description || "");
         } catch {
-          return [n, ""];
+          // unreadable SKILL.md: list it without a description
         }
+        return [n, description, src.refs(n).join(", ")];
       });
-      table(["name", "description"], rows);
+      table(["name", "description", "references"], rows);
     });
 
   skill
     .command("get")
-    .description("Print a skill's full content (markdown)")
+    .description("Print a skill's content (markdown), or one of its references")
     .argument("<name>", "skill name (e.g. core)")
-    .option(
-      "--full",
-      "Include reference files (reserved; currently equivalent to default)",
-    )
-    .action((name: string, _opts: { full?: boolean }) => {
+    .option("--ref <ref>", "print one reference instead (e.g. sandboxes, deploys, sdk)")
+    .option("--full", "append every reference after the skill")
+    .action((name: string, opts: { ref?: string; full?: boolean }) => {
       const src = getSource();
       try {
+        if (opts.ref) {
+          const md = readRef(src, name, opts.ref);
+          if (isJSONMode()) {
+            printJSON({ name, ref: opts.ref, path: src.pathOf(name, opts.ref), content: md });
+            return;
+          }
+          process.stdout.write(md.endsWith("\n") ? md : md + "\n");
+          return;
+        }
         const { md, meta } = readSkill(src, name);
+        let content = md;
+        if (opts.full) {
+          for (const ref of src.refs(name)) {
+            const body = src.readRef(name, ref) ?? "";
+            content = `${content.trimEnd()}\n\n---\n<!-- references/${ref}.md -->\n\n${body}`;
+          }
+        }
         if (isJSONMode()) {
           printJSON({
             name,
             path: src.pathOf(name),
             frontmatter: meta,
-            content: md,
+            content,
+            references: refEntries(src, name),
           });
           return;
         }
-        process.stdout.write(md.endsWith("\n") ? md : md + "\n");
+        process.stdout.write(content.endsWith("\n") ? content : content + "\n");
       } catch (e: any) {
         fail(e.message, 3);
       }
@@ -174,9 +247,10 @@ export function registerSkill(program: Command) {
     .command("path")
     .description("Print the filesystem path of a skill (or the skills root)")
     .argument("[name]", "skill name; omit to print the skills directory")
-    .action((name?: string) => {
+    .option("--ref <ref>", "print the path of one reference instead")
+    .action((name: string | undefined, opts: { ref?: string }) => {
       const src = getSource();
-      const target = src.pathOf(name);
+      const target = src.pathOf(name, name ? opts.ref : undefined);
       if (isJSONMode()) {
         printJSON({ path: target });
         return;

package/src/index.ts

@@ -38,6 +38,9 @@ const AGENTS_HELP = [
   chalk.dim(
     "  copy-paste examples. Prefer this over guessing commands from flag docs alone.",
   ),
+  chalk.dim(
+    "  For more depth: lizard skills get core --ref sandboxes | deploys | sdk",
+  ),
 ].join("\n");
 
 // Compact form of the same pointer, shown on every subcommand's `--help` so the
@@ -387,7 +390,7 @@ async function main() {
       version: CURRENT_VERSION,
       agents: {
         start: "lizard skills get core",
-        note: "Skills ship with this CLI version and cover sandboxes and the full app lifecycle (deploy, link, addons, logs, scaling, secrets, domains) with copy-paste examples. Prefer this over guessing commands from flag docs alone.",
+        note: "Skills ship with this CLI version and cover sandboxes and the full app lifecycle (deploy, link, addons, logs, scaling, secrets, domains) with copy-paste examples. Prefer this over guessing commands from flag docs alone. For more depth: `lizard skills get core --ref sandboxes|deploys|sdk`.",
       },
       command: dumpCommand(target),
       globalOptions: isRoot

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.44";
+export const CURRENT_VERSION = "4.0.45";
 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

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "vitest";
 import { EMBEDDED_SKILLS } from "../../src/lib/skills-data.generated.js";
 
-const core = EMBEDDED_SKILLS.core.content;
+const core = EMBEDDED_SKILLS.core;
+const files: Record<string, string> = {
+  "SKILL.md": core.content,
+  ...Object.fromEntries(Object.entries(core.references).map(([ref, md]) => [`references/${ref}.md`, md])),
+};
 
 /** GitHub-style heading slug, which the skill's own links use. */
 const slug = (h: string) => h.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
@@ -11,25 +15,40 @@ describe("the core skill", () => {
     expect(Object.keys(EMBEDDED_SKILLS)).toEqual(["core"]);
   });
 
-  test("covers sandboxes as well as deploys", () => {
-    expect(core).toContain("\n## Sandboxes\n");
-    for (const h of ["Quickstart", "Templates", "Running commands", "Files", "Ports", "Lifetime", "Snapshots and pause/resume", "From code: Lizard SDK"]) {
-      expect(core).toContain(`\n### ${h}\n`);
+  test("ships the sandboxes, deploys and sdk references, and names each one", () => {
+    expect(Object.keys(core.references).sort()).toEqual(["deploys", "sandboxes", "sdk"]);
+    for (const ref of Object.keys(core.references)) {
+      expect(core.content).toContain(`--ref ${ref}`);
     }
-    for (const h of ["Deploying", "Secrets", "Managed addons", "Sign-in", "Exit codes", "Default project", "Billing"]) {
-      expect(core).toContain(`\n## ${h}\n`);
+  });
+
+  test("covers the whole platform in SKILL.md", () => {
+    for (const h of ["Sign-in", "Exit codes", "Default project", "Sandboxes", "Deploys", "Databases and storage", "Secrets and config", "Domains", "Billing"]) {
+      expect(core.content).toContain(`\n## ${h}\n`);
     }
-    expect(core).not.toContain("lizard skills get sandbox");
+    expect(core.content).not.toContain("lizard skills get sandbox ");
+  });
+
+  test("keeps SKILL.md under 500 lines", () => {
+    const body = core.content.replace(/^---\n[\s\S]*?\n---\n/, "");
+    expect(body.split("\n").length).toBeLessThan(500);
   });
 
-  test("every #link points at a heading in the skill", () => {
-    const headings = new Set([...core.matchAll(/^#{2,4} (.+)$/gm)].map((m) => slug(m[1])));
-    const links = [...core.matchAll(/\]\(#([\w-]+)\)/g)].map((m) => m[1]);
+  test.each(Object.keys(files))("every #link in %s points at a heading in the same file", (file) => {
+    const md = files[file];
+    const headings = new Set([...md.matchAll(/^#{1,4} (.+)$/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("references never link to other files", () => {
+    for (const md of Object.values(core.references)) {
+      expect(md).not.toMatch(/\]\((?!https?:|#)[^)]+\)/);
+    }
+  });
+
   test("its description fits the 1024-character limit", () => {
-    const description = core.match(/^description: "(.*)"$/m)![1];
+    const description = core.content.match(/^description: "(.*)"$/m)![1];
     expect(description.length).toBeLessThanOrEqual(1024);
     expect(description).toMatch(/^Creates cloud sandboxes and deploys apps/);
   });