@headways/cli 0.3.0 → 0.4.1

package/dist/{api-2BK6MGZB.js → api-5EKGGFQ6.js}

@@ -2,8 +2,8 @@
 import {
   apiRequest,
   rawRequest
-} from "./chunk-HYEL7L5Z.js";
-import "./chunk-T2H7EXOV.js";
+} from "./chunk-2INXZHRG.js";
+import "./chunk-UUFIIGTZ.js";
 export {
   apiRequest,
   rawRequest

package/dist/{chunk-HYEL7L5Z.js → chunk-2INXZHRG.js}

@@ -2,7 +2,7 @@
 import {
   getApiUrl,
   requireAuth
-} from "./chunk-T2H7EXOV.js";
+} from "./chunk-UUFIIGTZ.js";
 
 // src/lib/api.ts
 async function rawRequest(path, token, options = {}, apiUrl) {

package/dist/{chunk-T2H7EXOV.js → chunk-UUFIIGTZ.js}

@@ -8,6 +8,7 @@ var HEADWAYS_DIR = join(homedir(), ".headways");
 var CONFIG_FILE = join(HEADWAYS_DIR, "config.json");
 var CATALOG_FILE = join(HEADWAYS_DIR, "catalog.json");
 var INSTALLED_DIR = join(HEADWAYS_DIR, "installed");
+var CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 function readConfig() {
   if (!existsSync(CONFIG_FILE)) return {};
   try {
@@ -42,6 +43,7 @@ export {
   CONFIG_FILE,
   CATALOG_FILE,
   INSTALLED_DIR,
+  CLAUDE_SKILLS_DIR,
   readConfig,
   writeConfig,
   getApiUrl,

package/dist/{chunk-OZULVVQC.js → chunk-XTEQBKIN.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
+  CLAUDE_SKILLS_DIR,
   HEADWAYS_DIR,
   getApiUrl,
   readConfig
-} from "./chunk-T2H7EXOV.js";
+} from "./chunk-UUFIIGTZ.js";
 
 // src/commands/sync/index.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, renameSync, rmSync as rmSync2 } from "fs";
-import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 import { createGunzip } from "zlib";
 import { Readable } from "stream";
@@ -53,9 +53,8 @@ function registerUninstallCommand(program) {
     removeHooks(CLAUDE_SETTINGS_GLOBAL);
     removeHooks(CLAUDE_SETTINGS_LOCAL);
     console.log("\u2713 Removed Claude Code hooks");
-    const skillsDir = join(homedir(), ".claude", "skills");
-    if (existsSync(skillsDir)) {
-      rmSync(skillsDir, { recursive: true, force: true });
+    if (existsSync(CLAUDE_SKILLS_DIR)) {
+      rmSync(CLAUDE_SKILLS_DIR, { recursive: true, force: true });
       console.log("\u2713 Removed ~/.claude/skills/");
     }
     const headwaysDir = join(homedir(), ".headways");
@@ -232,9 +231,8 @@ async function downloadAndMaterialize(slug, version, state, apiUrl) {
   });
   if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
   const buf = Buffer.from(await res.arrayBuffer());
-  const skillsDir = join2(homedir2(), ".claude", "skills");
-  const dest = join2(skillsDir, slug);
-  const staging = join2(skillsDir, `.${slug}-staging`);
+  const dest = join2(CLAUDE_SKILLS_DIR, slug);
+  const staging = join2(CLAUDE_SKILLS_DIR, `.${slug}-staging`);
   mkdirSync2(staging, { recursive: true });
   await extractTarGz(buf, staging);
   if (existsSync2(dest)) rmSync2(dest, { recursive: true });

package/dist/{config-SHMIVRAP.js → config-XQHAXREA.js}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   CATALOG_FILE,
+  CLAUDE_SKILLS_DIR,
   CONFIG_FILE,
   HEADWAYS_DIR,
   INSTALLED_DIR,
@@ -9,9 +10,10 @@ import {
   readConfig,
   requireAuth,
   writeConfig
-} from "./chunk-T2H7EXOV.js";
+} from "./chunk-UUFIIGTZ.js";
 export {
   CATALOG_FILE,
+  CLAUDE_SKILLS_DIR,
   CONFIG_FILE,
   HEADWAYS_DIR,
   INSTALLED_DIR,

package/dist/index.js

@@ -2,23 +2,25 @@
 import {
   apiRequest,
   rawRequest
-} from "./chunk-HYEL7L5Z.js";
+} from "./chunk-2INXZHRG.js";
 import {
   registerSetupCommand,
   registerSyncCommands,
   registerUninstallCommand
-} from "./chunk-OZULVVQC.js";
+} from "./chunk-XTEQBKIN.js";
 import {
+  CLAUDE_SKILLS_DIR,
   INSTALLED_DIR,
   getApiUrl,
   getAppUrl,
   readConfig,
   requireAuth,
   writeConfig
-} from "./chunk-T2H7EXOV.js";
+} from "./chunk-UUFIIGTZ.js";
 
 // src/index.ts
 import "dotenv/config";
+import { createRequire } from "module";
 import { program } from "commander";
 
 // src/commands/auth.ts
@@ -79,10 +81,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 +281,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 });
@@ -378,44 +384,82 @@ function registerImportCommand(program2) {
 import "commander";
 import * as fs3 from "fs/promises";
 import * as path3 from "path";
-import { watch } from "fs";
+import { watch, existsSync } from "fs";
+var catchMissing = (e) => {
+  if (e.code === "ENOENT") return null;
+  throw e;
+};
 async function readSkillDir(dir) {
   const skillMdPath = path3.join(dir, "SKILL.md");
-  const body = await fs3.readFile(skillMdPath, "utf-8").catch(() => "");
-  let headline;
-  const headwaysYamlPath = path3.join(dir, "headways.yaml");
+  let body;
   try {
-    const yaml = await fs3.readFile(headwaysYamlPath, "utf-8");
-    const match = yaml.match(/headline:\s*['"]?(.+?)['"]?\s*$/m);
-    if (match) headline = match[1] ?? void 0;
+    body = await fs3.readFile(skillMdPath, "utf-8");
   } catch {
+    throw new Error(`SKILL.md not found in ${dir}`);
   }
-  let capabilities;
-  const capYamlPath = path3.join(dir, "capabilities.yaml");
-  try {
-    const capYaml = await fs3.readFile(capYamlPath, "utf-8");
-    capabilities = { raw: capYaml };
-  } catch {
+  const [headwaysYaml, capabilitiesYaml, connectionsYaml] = await Promise.all([
+    fs3.readFile(path3.join(dir, "headways.yaml"), "utf-8").catch(catchMissing),
+    fs3.readFile(path3.join(dir, "capabilities.yaml"), "utf-8").catch(catchMissing),
+    fs3.readFile(path3.join(dir, "connections.yaml"), "utf-8").catch(catchMissing)
+  ]);
+  let headline;
+  if (headwaysYaml) {
+    const match = headwaysYaml.match(/headline:\s*['"]?(.+?)['"]?\s*$/m);
+    if (match) headline = match[1] ?? void 0;
+  }
+  let connections;
+  if (connectionsYaml) {
+    const items = parseConnectionsYaml(connectionsYaml);
+    if (items.length > 0) connections = items;
+  }
+  return { body, headline, capabilities: capabilitiesYaml ?? void 0, 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();
+    }
   }
-  return { body, headline, capabilities };
+  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`);
 }
+function resolveSkillDir(slug) {
+  if (!slug) return process.cwd();
+  const installedPath = path3.join(CLAUDE_SKILLS_DIR, slug);
+  if (existsSync(installedPath)) return installedPath;
+  return path3.join(process.cwd(), slug);
+}
 function registerPushCommand(program2) {
-  program2.command("push [slug]").description("Push local skill files as a draft to Headways").option("--watch", "Watch for file changes and auto-push").option("--dir <dir>", "Skill directory (default: ./<slug> or cwd)").action(async (slug, opts) => {
+  program2.command("push [slug]").description("Push local skill files as a draft to Headways").option("--watch", "Watch for file changes and auto-push").option("--dir <dir>", "Skill directory (default: installed location, then ./<slug>)").action(async (slug, opts) => {
     requireAuth();
     const resolvedSlug = slug ?? path3.basename(process.cwd());
-    const dir = opts.dir ?? (slug ? path3.join(process.cwd(), slug) : process.cwd());
+    const dir = opts.dir ?? resolveSkillDir(slug);
     await pushSkill(resolvedSlug, dir);
     if (opts.watch) {
       console.log(`Watching ${dir} for changes...`);
@@ -469,6 +513,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 +555,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, atlassian, linear, notion, google-drive, stripe, asana, hubspot, datadog)
+  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 +624,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) {
@@ -576,8 +636,8 @@ function registerSkillsCommands(program2) {
     console.log(SKILLS_GUIDE);
   });
   skills.command("list").description("List skills in the active org").action(async () => {
-    const { requireAuth: requireAuth2 } = await import("./config-SHMIVRAP.js");
-    const { apiRequest: apiRequest2 } = await import("./api-2BK6MGZB.js");
+    const { requireAuth: requireAuth2 } = await import("./config-XQHAXREA.js");
+    const { apiRequest: apiRequest2 } = await import("./api-5EKGGFQ6.js");
     requireAuth2();
     const result = await apiRequest2("/v1/skills");
     if (result.data.length === 0) {
@@ -589,8 +649,25 @@ 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");
+    const { acceptSkill } = await import("./sync-Q3OQUWOD.js");
     await acceptSkill(slug);
+    try {
+      const { apiRequest: apiRequest2 } = await import("./api-5EKGGFQ6.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 +693,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) {
@@ -657,7 +756,7 @@ function registerEmitCommand(program2) {
 }
 
 // src/commands/prime.ts
-import { existsSync, readdirSync, readFileSync } from "fs";
+import { existsSync as existsSync2, readdirSync, readFileSync } from "fs";
 import "commander";
 function registerPrimeCommand(program2) {
   program2.command("prime").description("Output Headways workflow context for AI coding assistants").action(() => {
@@ -720,6 +819,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", "");
@@ -729,7 +832,7 @@ function registerPrimeCommand(program2) {
   });
 }
 function getInstalledSkills() {
-  if (!existsSync(INSTALLED_DIR)) return [];
+  if (!existsSync2(INSTALLED_DIR)) return [];
   try {
     return readdirSync(INSTALLED_DIR).filter((f) => f.endsWith(".json")).map((f) => {
       const slug = f.replace(/\.json$/, "");
@@ -739,7 +842,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;
@@ -751,9 +855,12 @@ function getInstalledSkills() {
 }
 
 // src/index.ts
-program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version("0.2.1");
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version(version);
 registerAuthCommands(program);
 registerSkillsCommands(program);
+registerConnectionsCommands(program);
 registerSyncCommands(program);
 registerEmitCommand(program);
 registerPrimeCommand(program);

package/dist/{sync-6PKI35ZY.js → sync-Q3OQUWOD.js}

@@ -5,8 +5,8 @@ import {
   registerDevice,
   registerSyncCommands,
   writeSyncState
-} from "./chunk-OZULVVQC.js";
-import "./chunk-T2H7EXOV.js";
+} from "./chunk-XTEQBKIN.js";
+import "./chunk-UUFIIGTZ.js";
 export {
   acceptSkill,
   readSyncState,

package/package.json

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