@homespunapps/cli 1.6.42 → 1.6.44

package/dist/commands/skill.js

@@ -7,14 +7,19 @@
 // agent always reads what the relay it's actually talking to wants it
 // to read.
 //
-// Two verbs:
-//   `homespun skill show`      — print the full markdown to stdout (the
+// Three verbs:
+//   `homespun skill show`      print the full markdown to stdout (the
 //                            install / refresh path; pipe to a file).
-//   `homespun skill version`   — print just the relay's skill version (the
+//                            `--section <slug>` prints one reference section
+//                            instead, which is how an agent holding the skill
+//                            as a fetched blob follows a pointer that a
+//                            file-based agent would follow with a plain read.
+//   `homespun skill version`   print just the relay's skill version (the
 //                            "is my local copy stale?" probe). The agent
 //                            compares this to the `<!-- homespun skill v… -->`
 //                            comment in its local skill file and re-runs
 //                            `homespun skill show > <path>` when they differ.
+//   `homespun skill sections`  list the reference sections that exist.
 //
 // Both are unauthenticated — the skill route is public on the relay and
 // an agent on a too-old CLI must be able to read the upgrade instructions
@@ -46,11 +51,22 @@ async function failOnNon2xx(res, target) {
     const body = await res.text().catch(() => "");
     fail(`relay returned ${res.status} for ${target}${body ? ": " + body.slice(0, 200) : ""}`, "relay_error");
 }
-// `homespun skill show` — print the full skill.
+// `homespun skill show [--section <slug>]`: print the full skill, or one
+// reference section of it.
+//
+// SKILL.md carries pointers to sections it does not include, so that an agent
+// pays for them only when it needs them. An agent holding the skill as files on
+// disk follows such a pointer by reading references/<slug>.md; an agent that
+// fetched the skill over the wire has no such file, and `--section` is how it
+// follows the same pointer. Without it the pointer would dangle for exactly the
+// consumers this command exists to serve.
 async function runSkillFetch(args) {
     assertKnownFlags(args, ...specFor("skill", "show"));
     const url = resolveRelayUrl(args);
-    const target = url + "/skills/homespun/SKILL.md";
+    const section = args.flags.get("section");
+    const target = section === undefined
+        ? url + "/skills/homespun/SKILL.md"
+        : `${url}/skills/homespun/references/${encodeURIComponent(section)}.md`;
     const res = await fetchOrFail(target);
     await failOnNon2xx(res, target);
     const text = await res.text();
@@ -61,6 +77,18 @@ async function runSkillFetch(args) {
     if (!text.endsWith("\n"))
         process.stdout.write("\n");
 }
+// `homespun skill sections`: list the reference sections available. The index
+// an agent needs when it holds SKILL.md as a fetched blob rather than a tree.
+async function runSkillSections(args) {
+    assertKnownFlags(args, ...specFor("skill", "sections"));
+    const url = resolveRelayUrl(args);
+    const target = url + "/skills/homespun/references";
+    const res = await fetchOrFail(target);
+    await failOnNon2xx(res, target);
+    const body = (await res.json());
+    const sections = Array.isArray(body.sections) ? body.sections : [];
+    process.stdout.write(JSON.stringify({ sections }) + "\n");
+}
 // `homespun skill version [--plain]` — print just the version.
 async function runSkillVersion(args) {
     assertKnownFlags(args, ...specFor("skill", "version"));
@@ -100,10 +128,13 @@ export async function runSkill(args) {
         case "version":
             await runSkillVersion(args);
             break;
+        case "sections":
+            await runSkillSections(args);
+            break;
         case undefined:
-            fail("missing verb — usage: homespun skill <show|version> (run 'homespun skill --help')", "invalid_args");
+            fail("missing verb. Usage: homespun skill <show|version|sections> (run 'homespun skill --help')", "invalid_args");
             break;
         default:
-            fail(`unknown skill verb '${sub}' — expected show|version (run 'homespun skill --help')`, "invalid_args");
+            fail(`unknown skill verb '${sub}': expected show|version|sections (run 'homespun skill --help')`, "invalid_args");
     }
 }

package/dist/help-catalog.js

@@ -769,11 +769,18 @@ const SKILL = {
     noun: "skill",
     tagline: "the relay's SKILL.md",
     group: "other",
-    rootSummary: "The relay's SKILL.md: show, version. Auto-updating, and no API key is required.",
+    rootSummary: "The relay's SKILL.md: show, version, sections. Auto-updating, and no API key is required.",
     verbs: [
         {
             verb: "show",
             summary: "Fetches the relay's SKILL.md and writes the raw markdown to stdout.",
+            flags: [
+                {
+                    name: "section",
+                    value: "<slug>",
+                    description: "Fetch one reference section instead of the whole skill (see 'skill sections')",
+                },
+            ],
         },
         {
             verb: "version",
@@ -785,6 +792,10 @@ const SKILL = {
                 },
             ],
         },
+        {
+            verb: "sections",
+            summary: "Lists the reference sections SKILL.md points at but does not include.",
+        },
     ],
     notes: [
         "The skill is auto-updating: the relay's deployed image owns both the body and the version, so this is always the skill that matches the relay you are talking to.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.42",
+  "version": "1.6.44",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.42",
+    "@homespunapps/core": "^1.6.44",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {