@headways/cli 0.3.0 → 0.4.0

package/dist/index.js

@@ -79,10 +79,7 @@ function registerAuthCommands(program2) {
   });
   configure.command("clear").description("Clear credentials and reset setup state (keeps API and app URLs)").action(() => {
     const cfg = readConfig();
-    const cleared = {};
-    if (cfg.apiUrl) cleared.apiUrl = cfg.apiUrl;
-    if (cfg.appUrl) cleared.appUrl = cfg.appUrl;
-    writeConfig(cleared);
+    writeConfig({ apiUrl: cfg.apiUrl, appUrl: cfg.appUrl });
     console.log("Credentials cleared. The desktop app will show onboarding on next launch.");
   });
   configure.command("status").description("Show current API key and org").action(() => {
@@ -282,6 +279,13 @@ runtimes: [claude-code]
     kind: outcome
     description: 'Captures the main output artifact'
     schema: {}
+`
+    );
+    await fs.writeFile(
+      path.join(dir, "connections.yaml"),
+      `# connections:
+#   - connector: slack
+#     purpose: "Post skill output to a Slack channel"
 `
     );
     await fs.mkdir(path.join(dir, "fixtures"), { recursive: true });
@@ -397,16 +401,47 @@ async function readSkillDir(dir) {
     capabilities = { raw: capYaml };
   } catch {
   }
-  return { body, headline, capabilities };
+  let connections;
+  const connYamlPath = path3.join(dir, "connections.yaml");
+  try {
+    const connYaml = await fs3.readFile(connYamlPath, "utf-8");
+    const items = parseConnectionsYaml(connYaml);
+    if (items.length > 0) connections = items;
+  } catch {
+  }
+  return { body, headline, capabilities, connections };
+}
+function parseConnectionsYaml(yaml) {
+  const items = [];
+  const connectorRe = /^\s*-\s+connector:\s*(.+)$/;
+  const purposeRe = /^\s+purpose:\s*["']?(.+?)["']?\s*$/;
+  const lines = yaml.split("\n");
+  let current = null;
+  for (const line of lines) {
+    if (line.trimStart().startsWith("#")) continue;
+    const connMatch = connectorRe.exec(line);
+    if (connMatch) {
+      if (current?.connector && current.purpose) items.push(current);
+      current = { connector: (connMatch[1] ?? "").trim() };
+      continue;
+    }
+    if (current) {
+      const purposeMatch = purposeRe.exec(line);
+      if (purposeMatch) current.purpose = (purposeMatch[1] ?? "").trim();
+    }
+  }
+  if (current?.connector && current.purpose) items.push(current);
+  return items;
 }
 async function pushSkill(slug, dir) {
-  const { body, headline, capabilities } = await readSkillDir(dir);
+  const { body, headline, capabilities, connections } = await readSkillDir(dir);
   await apiRequest(`/v1/skills/${slug}/draft`, {
     method: "PUT",
     body: JSON.stringify({
       body,
       ...headline ? { headline } : {},
-      ...capabilities ? { capabilities } : {}
+      ...capabilities ? { capabilities } : {},
+      ...connections ? { connections } : {}
     })
   });
   console.log(`Pushed '${slug}' draft`);
@@ -469,6 +504,7 @@ headways skills push <slug>   # push local edits as a draft
   SKILL.md            # skill body \u2014 instructions for the AI agent
   headways.yaml       # metadata: slug, name, headline, channel, runtimes
   capabilities.yaml   # what the skill is allowed to do
+  connections.yaml    # MCP connectors this skill requires (optional)
   hooks.yaml          # structured hooks the skill exposes (optional)
 \`\`\`
 
@@ -510,6 +546,20 @@ data_classes: none  # none | pii | phi | pci
 auto_send: false    # true = skill may act without user confirmation
 \`\`\`
 
+### connections.yaml (required for any skill that uses MCP connector tools)
+
+Declare every MCP connector the skill depends on. Users see this list on \`headways skills accept\`
+and the Headways app gates installation on the connectors being configured.
+
+\`\`\`yaml
+- connector: slack    # connector identifier (e.g. slack, github, jira, linear, notion, google-drive)
+  purpose: Read channel messages and threads via Slack MCP tools
+- connector: github
+  purpose: Read pull requests and issues
+\`\`\`
+
+Omit the file entirely if the skill has no connector dependencies.
+
 ### hooks.yaml (omit if unused)
 
 \`\`\`yaml
@@ -565,6 +615,7 @@ local edits with \`headways skills push <slug>\`.
 - Headline > 90 chars \u2192 submit blocked with 422. Shorten before pushing.
 - Uppercase or special chars in slug \u2192 rejected at creation. Use \`a-z\`, \`0-9\`, \`-\` only.
 - Missing \`capabilities.yaml\` entries \u2192 skill silently blocked at runtime.
+- Missing \`connections.yaml\` for MCP-dependent skills \u2192 users install the skill but hit tool-not-found errors at runtime with no explanation. Always create this file when the skill calls MCP tools.
 - Passive or noun-phrase headline \u2192 poor discoverability; rewrite as a verb phrase.
 `.trim();
 function registerSkillsCommands(program2) {
@@ -591,6 +642,23 @@ function registerSkillsCommands(program2) {
   skills.command("accept <slug>").description("Accept a pending skill update and install it locally").action(async (slug) => {
     const { acceptSkill } = await import("./sync-6PKI35ZY.js");
     await acceptSkill(slug);
+    try {
+      const { apiRequest: apiRequest2 } = await import("./api-2BK6MGZB.js");
+      const metadata = await apiRequest2(`/v1/skills/${slug}/bundle/metadata`);
+      const reqs = metadata.connectionRequirements ?? [];
+      if (reqs.length > 0) {
+        console.log("");
+        console.log("This skill requires the following connectors:");
+        console.log("");
+        for (const req of reqs) {
+          console.log(`  - ${req.connector.padEnd(20)} ${req.purpose}`);
+        }
+        console.log("");
+        console.log("To authorize these connectors, use the Headways desktop app");
+        console.log("or run: headways connections add <provider>");
+      }
+    } catch {
+    }
   });
   skills.command("feedback <slug>").description("Submit feedback about a skill").option(
     "--reaction <type>",
@@ -616,6 +684,28 @@ function registerSkillsCommands(program2) {
   });
 }
 
+// src/commands/connections/index.ts
+import "commander";
+function registerConnectionsCommands(program2) {
+  const connections = program2.command("connections").description("Manage connector authorizations");
+  connections.command("add [provider]").description("Authorize a connector (opens the desktop app)").action((provider) => {
+    const target = provider ? `the ${provider} connector` : "connectors";
+    console.log(`To authorize ${target}, open the Headways desktop app.`);
+    console.log("");
+    console.log("  1. Open Headways");
+    console.log("  2. Go to Settings \u2192 Connections");
+    console.log('  3. Click "Connect" next to the connector you want to authorize');
+    console.log("");
+    console.log(
+      "Alternatively, install a skill that requires the connector and it will be set up automatically."
+    );
+  });
+  connections.command("list").description("List authorized connections (opens the desktop app)").action(() => {
+    console.log("To view your connections, open the Headways desktop app.");
+    console.log("Go to Settings \u2192 Connections to see and manage your authorized connectors.");
+  });
+}
+
 // src/sdk/emit.ts
 import "commander";
 function registerEmitCommand(program2) {
@@ -720,6 +810,10 @@ function registerPrimeCommand(program2) {
       for (const skill of skills) {
         const runLine = skill.lastRunAt ? `last run ${new Date(skill.lastRunAt).toLocaleDateString()}` : "never run";
         lines.push(`- **${skill.slug}** v${skill.version} (${skill.runtime}, ${runLine})`);
+        if (skill.connectionRequirements.length > 0) {
+          const connectors = skill.connectionRequirements.map((r) => r.connector).join(", ");
+          lines.push(`  - Requires connectors: ${connectors}`);
+        }
       }
     }
     lines.push("", "## Skill Files", "");
@@ -739,7 +833,8 @@ function getInstalledSkills() {
           slug,
           version: String(raw.version ?? ""),
           runtime: String(raw.runtime ?? "claude-code"),
-          lastRunAt: raw.last_run_at ?? null
+          lastRunAt: raw.last_run_at ?? null,
+          connectionRequirements: Array.isArray(raw.connection_requirements) ? raw.connection_requirements : []
         };
       } catch {
         return null;
@@ -754,6 +849,7 @@ function getInstalledSkills() {
 program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version("0.2.1");
 registerAuthCommands(program);
 registerSkillsCommands(program);
+registerConnectionsCommands(program);
 registerSyncCommands(program);
 registerEmitCommand(program);
 registerPrimeCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headways/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Headways CLI — authoring, sync, and runtime SDK",
   "license": "MIT",