@headways/cli 0.1.0

package/dist/api-WUIL5TMR.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import {
+  apiRequest,
+  rawRequest
+} from "./chunk-QXOLSB3Q.js";
+import "./chunk-VLKLEV4U.js";
+export {
+  apiRequest,
+  rawRequest
+};

package/dist/chunk-QXOLSB3Q.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import {
+  getApiUrl,
+  requireAuth
+} from "./chunk-VLKLEV4U.js";
+
+// src/lib/api.ts
+async function rawRequest(path, token, options = {}, apiUrl) {
+  const url = `${apiUrl ?? getApiUrl()}${path}`;
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...options.headers
+    }
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`API ${res.status}: ${body}`);
+  }
+  return res.json();
+}
+async function apiRequest(path, options = {}) {
+  const { token } = requireAuth();
+  return rawRequest(path, token, options);
+}
+
+export {
+  rawRequest,
+  apiRequest
+};

package/dist/chunk-VLKLEV4U.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+// src/lib/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+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");
+function readConfig() {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(cfg) {
+  if (!existsSync(HEADWAYS_DIR)) mkdirSync(HEADWAYS_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
+}
+function getApiUrl() {
+  const cfg = readConfig();
+  return cfg.apiUrl ?? process.env["HEADWAYS_API_URL"] ?? "https://api.headways.ai";
+}
+function requireAuth() {
+  const cfg = readConfig();
+  if (!cfg.token || !cfg.orgId) {
+    console.error("No API key configured. Run: headways configure");
+    process.exit(1);
+  }
+  return { token: cfg.token, orgId: cfg.orgId };
+}
+
+export {
+  HEADWAYS_DIR,
+  CONFIG_FILE,
+  CATALOG_FILE,
+  INSTALLED_DIR,
+  readConfig,
+  writeConfig,
+  getApiUrl,
+  requireAuth
+};

package/dist/config-GRE3MIQL.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import {
+  CATALOG_FILE,
+  CONFIG_FILE,
+  HEADWAYS_DIR,
+  INSTALLED_DIR,
+  getApiUrl,
+  readConfig,
+  requireAuth,
+  writeConfig
+} from "./chunk-VLKLEV4U.js";
+export {
+  CATALOG_FILE,
+  CONFIG_FILE,
+  HEADWAYS_DIR,
+  INSTALLED_DIR,
+  getApiUrl,
+  readConfig,
+  requireAuth,
+  writeConfig
+};

package/dist/index.js

@@ -0,0 +1,783 @@
+#!/usr/bin/env node
+import {
+  apiRequest,
+  rawRequest
+} from "./chunk-QXOLSB3Q.js";
+import {
+  HEADWAYS_DIR,
+  getApiUrl,
+  readConfig,
+  requireAuth,
+  writeConfig
+} from "./chunk-VLKLEV4U.js";
+
+// src/index.ts
+import "dotenv/config";
+import { program } from "commander";
+
+// src/commands/auth.ts
+import "commander";
+import * as readline from "readline/promises";
+async function promptApiKey(opts) {
+  let token = opts.token;
+  if (!token) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    token = (await rl.question("API key (sk_\u2026): ")).trim();
+    rl.close();
+  }
+  if (!token) {
+    console.error("No API key provided.");
+    process.exit(1);
+  }
+  return token;
+}
+function registerAuthCommands(program2) {
+  const configure = program2.command("configure").description("Set your Headways API key and optional API URL").option("--token <token>", "API key (skip interactive prompt)").option("--api-url <url>", "API base URL (default: https://api.headways.ai)").option("--app-url <url>", "Web app URL (default: https://app.headways.ai)").action(async (opts) => {
+    const token = await promptApiKey(opts);
+    const cfg = readConfig();
+    if (opts.apiUrl) cfg.apiUrl = opts.apiUrl;
+    if (opts.appUrl) cfg.appUrl = opts.appUrl;
+    try {
+      const me = await rawRequest(
+        "/v1/me",
+        token,
+        {},
+        cfg.apiUrl
+      );
+      cfg.token = token;
+      if (me.type === "api_key" && me.organization) {
+        cfg.orgSlug = me.organization.slug;
+        cfg.orgId = me.organization.id;
+      }
+      writeConfig(cfg);
+      console.log(me.type === "api_key" && me.organization ? `API key saved. Org: ${me.organization.slug}` : "API key saved.");
+    } catch {
+      console.error("Invalid API key. Not saved. Check the key and try again.");
+      process.exit(1);
+    }
+  });
+  configure.command("status").description("Show current API key and org").action(() => {
+    const cfg = readConfig();
+    if (!cfg.token) {
+      console.log("No API key configured. Run `headways configure`.");
+    } else {
+      console.log(`API key: ${cfg.token.slice(0, 12)}\u2026 | Org: ${cfg.orgSlug ?? "(none set)"} | API: ${cfg.apiUrl ?? "https://api.headways.ai"}`);
+    }
+  });
+  configure.command("clear").description("Remove stored API key and org").action(() => {
+    const cfg = readConfig();
+    delete cfg.token;
+    delete cfg.orgSlug;
+    delete cfg.orgId;
+    writeConfig(cfg);
+    console.log("Configuration cleared.");
+  });
+  program2.command("org").description("Manage org context").command("use <slug>").description("Set active org by slug").action(async (slug) => {
+    const cfg = readConfig();
+    if (!cfg.token) {
+      console.error("No API key configured. Run `headways configure` first.");
+      process.exit(1);
+    }
+    try {
+      await rawRequest("/v1/me", cfg.token);
+    } catch {
+      console.error("Invalid API key. Run `headways configure` again.");
+      process.exit(1);
+    }
+    cfg.orgSlug = slug;
+    writeConfig(cfg);
+    console.log(`Active org set to: ${slug}`);
+  });
+}
+
+// src/commands/skills/index.ts
+import "commander";
+
+// src/commands/skills/new.ts
+import "commander";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as readline2 from "readline/promises";
+function registerNewCommand(program2) {
+  program2.command("new").description("Create a new skill scaffold in the current directory").option("--slug <slug>", "Skill slug").option("--headline <headline>", "Verb-first headline").action(async (opts) => {
+    requireAuth();
+    const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
+    const slug = opts.slug ?? (await rl.question("Slug (e.g. email-triage): ")).trim();
+    const headline = opts.headline ?? (await rl.question("Headline (verb-first, \u226490 chars): ")).trim();
+    rl.close();
+    if (!slug || !headline) {
+      console.error("slug and headline are required.");
+      process.exit(1);
+    }
+    const dir = path.join(process.cwd(), slug);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(
+      path.join(dir, "SKILL.md"),
+      `---
+description: ${headline}
+allowed_tools:
+  - Read
+---
+
+# ${slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
+
+[Add your skill instructions here]
+`
+    );
+    await fs.writeFile(
+      path.join(dir, "headways.yaml"),
+      `slug: ${slug}
+name: ${slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}
+headline: '${headline}'
+channel: prompt
+runtimes: [claude-code]
+`
+    );
+    await fs.writeFile(
+      path.join(dir, "capabilities.yaml"),
+      `capabilities:
+  reads: []
+  writes: []
+  external: []
+  data_classes: []
+  auto_send: false
+`
+    );
+    await fs.writeFile(
+      path.join(dir, "hooks.yaml"),
+      `hooks:
+  - name: outcome
+    kind: outcome
+    description: 'Captures the main output artifact'
+    schema: {}
+`
+    );
+    await fs.mkdir(path.join(dir, "fixtures"), { recursive: true });
+    try {
+      await apiRequest("/v1/skills", {
+        method: "POST",
+        body: JSON.stringify({
+          slug,
+          name: slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+          headline
+        })
+      });
+      console.log(`\u2713 Skill '${slug}' scaffolded and registered at ${dir}`);
+    } catch {
+      console.log(
+        `\u2713 Skill '${slug}' scaffolded at ${dir} (not yet synced \u2014 run 'headways skills push' to register)`
+      );
+    }
+  });
+}
+
+// src/commands/skills/import.ts
+import "commander";
+import * as fs2 from "fs/promises";
+import * as path2 from "path";
+var ORG_PROFILES = {
+  hippocratic: {
+    connectorHints: ["ehr.read", "ehr.write", "phi.access"],
+    fixtureTemplate: "patient-encounter",
+    channelPolicy: "stable"
+  },
+  revive: {
+    connectorHints: ["email.read", "calendar.read", "ads.read"],
+    fixtureTemplate: "campaign-brief",
+    channelPolicy: "beta"
+  }
+};
+function registerImportCommand(program2) {
+  program2.command("import <path>").description("Import a skill from a file, directory, or URL").option("--slug <slug>", "Override derived slug").option(
+    "--org <orgProfile>",
+    "Apply org-specific connector hints + fixture templates (hippocratic, revive)"
+  ).action(async (inputPath, opts) => {
+    requireAuth();
+    let source;
+    let format = "auto";
+    try {
+      const stat2 = await fs2.stat(inputPath);
+      if (stat2.isDirectory()) {
+        const skillMdPath = path2.join(inputPath, "SKILL.md");
+        source = await fs2.readFile(skillMdPath, "utf-8");
+        format = "skill-md";
+      } else {
+        source = await fs2.readFile(inputPath, "utf-8");
+        if (inputPath.endsWith(".yaml") || inputPath.endsWith(".yml")) {
+          format = "headways-yaml";
+        } else {
+          format = "markdown";
+        }
+      }
+    } catch {
+      console.error(`Cannot read '${inputPath}': file or directory not found.`);
+      process.exit(1);
+    }
+    const profile = opts.org ? ORG_PROFILES[opts.org] : void 0;
+    if (opts.org && !profile) {
+      console.warn(
+        `Unknown org profile '${opts.org}'. Known profiles: ${Object.keys(ORG_PROFILES).join(", ")}`
+      );
+    }
+    const derivedSlug = opts.slug ?? path2.basename(inputPath, path2.extname(inputPath)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const result = await apiRequest("/v1/skills/import", {
+      method: "POST",
+      body: JSON.stringify({
+        source,
+        format,
+        suggestedSlug: derivedSlug,
+        connectorHints: profile?.connectorHints,
+        channelPolicy: profile?.channelPolicy
+      })
+    });
+    console.log(`Imported as '${result.slug}' (format: ${result.detectedFormat})`);
+    console.log(`  Headline: ${result.headline}`);
+    console.log(`  Skill ID: ${result.skillId}`);
+    if (profile) {
+      console.log(`  Org profile: ${opts.org}`);
+      console.log(`  Connector hints: ${profile.connectorHints.join(", ")}`);
+      console.log(`  Fixture template: ${profile.fixtureTemplate}`);
+    }
+    console.log(`  Run 'headways skills push ${result.slug}' to sync edits.`);
+  });
+}
+
+// src/commands/skills/push.ts
+import "commander";
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+import { watch } from "fs";
+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");
+  try {
+    const yaml = await fs3.readFile(headwaysYamlPath, "utf-8");
+    const match = yaml.match(/headline:\s*['"]?(.+?)['"]?\s*$/m);
+    if (match) headline = match[1] ?? void 0;
+  } catch {
+  }
+  let capabilities;
+  const capYamlPath = path3.join(dir, "capabilities.yaml");
+  try {
+    const capYaml = await fs3.readFile(capYamlPath, "utf-8");
+    capabilities = { raw: capYaml };
+  } catch {
+  }
+  return { body, headline, capabilities };
+}
+async function pushSkill(slug, dir) {
+  const { body, headline, capabilities } = await readSkillDir(dir);
+  await apiRequest(`/v1/skills/${slug}/draft`, {
+    method: "PUT",
+    body: JSON.stringify({
+      body,
+      ...headline ? { headline } : {},
+      ...capabilities ? { capabilities } : {}
+    })
+  });
+  console.log(`Pushed '${slug}' draft`);
+}
+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) => {
+    requireAuth();
+    const resolvedSlug = slug ?? path3.basename(process.cwd());
+    const dir = opts.dir ?? (slug ? path3.join(process.cwd(), slug) : process.cwd());
+    await pushSkill(resolvedSlug, dir);
+    if (opts.watch) {
+      console.log(`Watching ${dir} for changes...`);
+      let debounceTimer = null;
+      watch(dir, { recursive: true }, () => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(async () => {
+          try {
+            await pushSkill(resolvedSlug, dir);
+          } catch (err) {
+            console.error("Push failed:", err.message);
+          }
+        }, 300);
+      });
+      await new Promise(() => {
+      });
+    }
+  });
+}
+
+// src/commands/skills/capture.ts
+import "commander";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
+import { homedir } from "os";
+var SETTINGS_PATH = path4.join(homedir(), ".claude", "settings.json");
+async function readSettingsJson() {
+  try {
+    const raw = await fs4.readFile(SETTINGS_PATH, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeSettingsJson(settings) {
+  await fs4.mkdir(path4.dirname(SETTINGS_PATH), { recursive: true });
+  await fs4.writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+}
+async function injectCaptureHooks(slug, apiUrl, token) {
+  const settings = await readSettingsJson();
+  const hooks = settings["hooks"] ?? {};
+  const postToolUse = hooks["PostToolUse"] ?? [];
+  const preToolUse = hooks["PreToolUse"] ?? [];
+  const postHookId = `headways-capture-post-${slug}`;
+  const preHookId = `headways-capture-pre-${slug}`;
+  if (!postToolUse.some((h) => h["id"] === postHookId)) {
+    postToolUse.push({
+      id: postHookId,
+      matcher: "*",
+      hooks: [
+        {
+          type: "command",
+          command: `headways capture-record --slug ${slug} --event tool.{{tool_name}} --status {{tool_result_is_error}} 2>/dev/null || true`
+        }
+      ]
+    });
+  }
+  if (!preToolUse.some((h) => h["id"] === preHookId)) {
+    preToolUse.push({
+      id: preHookId,
+      matcher: "*",
+      hooks: [
+        {
+          type: "command",
+          command: `headways capture-record --slug ${slug} --event tool.pre.{{tool_name}} 2>/dev/null || true`
+        }
+      ]
+    });
+  }
+  hooks["PostToolUse"] = postToolUse;
+  hooks["PreToolUse"] = preToolUse;
+  settings["hooks"] = hooks;
+  await writeSettingsJson(settings);
+  console.log(`Injected capture hooks for ${slug} into ${SETTINGS_PATH}`);
+}
+async function removeCaptureHooks(slug) {
+  const settings = await readSettingsJson();
+  const hooks = settings["hooks"] ?? {};
+  const postHookId = `headways-capture-post-${slug}`;
+  const preHookId = `headways-capture-pre-${slug}`;
+  if (Array.isArray(hooks["PostToolUse"])) {
+    hooks["PostToolUse"] = hooks["PostToolUse"].filter(
+      (h) => h["id"] !== postHookId
+    );
+  }
+  if (Array.isArray(hooks["PreToolUse"])) {
+    hooks["PreToolUse"] = hooks["PreToolUse"].filter(
+      (h) => h["id"] !== preHookId
+    );
+  }
+  settings["hooks"] = hooks;
+  await writeSettingsJson(settings);
+  console.log(`Removed capture hooks for ${slug}`);
+}
+function registerCaptureCommand(program2) {
+  program2.command("capture <slug>").description("Capture a live skill run session and upload as sample run").option("--version <version>", "Skill version to capture against", "draft").option("--stop", "Stop capturing and upload the session").action(async (slug, opts) => {
+    const { token, orgId } = requireAuth();
+    const apiUrl = getApiUrl();
+    if (opts.stop) {
+      await removeCaptureHooks(slug);
+      const sessionFile2 = path4.join(homedir(), ".headways", `capture-${slug}.json`);
+      let session = null;
+      try {
+        const raw = await fs4.readFile(sessionFile2, "utf8");
+        session = JSON.parse(raw);
+      } catch {
+        console.error("No active capture session found. Run `headways capture <slug>` first.");
+        process.exit(1);
+      }
+      const res = await fetch(
+        `${apiUrl}/v1/skills/${slug}/versions/${opts.version ?? "draft"}/sample-run/capture-upload`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+            "x-headways-org-id": orgId
+          },
+          body: JSON.stringify(session)
+        }
+      );
+      if (!res.ok) {
+        console.error(`Upload failed: ${res.status} ${await res.text()}`);
+        process.exit(1);
+      }
+      const result = await res.json();
+      await fs4.unlink(sessionFile2).catch(() => {
+      });
+      console.log(`Capture uploaded. Run ID: ${result.skillRunId}`);
+      return;
+    }
+    await injectCaptureHooks(slug, apiUrl, token);
+    const sessionFile = path4.join(homedir(), ".headways", `capture-${slug}.json`);
+    await fs4.mkdir(path4.dirname(sessionFile), { recursive: true });
+    await fs4.writeFile(
+      sessionFile,
+      JSON.stringify(
+        {
+          skill_slug: slug,
+          version: opts.version ?? "draft",
+          invocation_prompt: "",
+          tool_calls: [],
+          hook_emissions: [],
+          fixture_reads: [],
+          artifact_writes: [],
+          duration_ms: 0,
+          captured_at: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      )
+    );
+    console.log(`Capturing ${slug}. Run the skill in Claude Code, then stop with:`);
+    console.log(`  headways capture ${slug} --stop`);
+  });
+}
+
+// src/commands/skills/index.ts
+function registerSkillsCommands(program2) {
+  const skills = program2.command("skills").description("Manage skills");
+  registerNewCommand(skills);
+  registerImportCommand(skills);
+  registerPushCommand(skills);
+  registerCaptureCommand(program2);
+  skills.command("list").description("List skills in the active org").action(async () => {
+    const { requireAuth: requireAuth2 } = await import("./config-GRE3MIQL.js");
+    const { apiRequest: apiRequest2 } = await import("./api-WUIL5TMR.js");
+    requireAuth2();
+    const result = await apiRequest2("/v1/skills");
+    if (result.data.length === 0) {
+      console.log("No skills found.");
+    } else {
+      for (const s of result.data) {
+        console.log(`  ${s.slug.padEnd(30)} ${s.headline}`);
+      }
+    }
+  });
+}
+
+// src/commands/sync/index.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join5 } from "path";
+import { createGunzip } from "zlib";
+import { Readable } from "stream";
+import "stream/promises";
+import "commander";
+var PENDING_FILE = join5(HEADWAYS_DIR, "pending.json");
+var SYNC_STATE_FILE = join5(HEADWAYS_DIR, "sync-state.json");
+var INSTALLED_DIR = join5(HEADWAYS_DIR, "installed");
+function readSyncState() {
+  if (!existsSync(SYNC_STATE_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(SYNC_STATE_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeSyncState(state) {
+  if (!existsSync(HEADWAYS_DIR)) mkdirSync(HEADWAYS_DIR, { recursive: true });
+  writeFileSync(SYNC_STATE_FILE, JSON.stringify(state, null, 2) + "\n");
+}
+function readPending() {
+  if (!existsSync(PENDING_FILE)) return [];
+  try {
+    return JSON.parse(readFileSync(PENDING_FILE, "utf8"));
+  } catch {
+    return [];
+  }
+}
+function writePending(updates) {
+  if (!existsSync(HEADWAYS_DIR)) mkdirSync(HEADWAYS_DIR, { recursive: true });
+  writeFileSync(PENDING_FILE, JSON.stringify(updates, null, 2) + "\n");
+}
+function deviceHeaders(state) {
+  return {
+    Authorization: `Bearer ${state.device_token ?? ""}`,
+    "x-headways-device-id": state.device_id ?? "",
+    "x-headways-timestamp": String(Math.floor(Date.now() / 1e3))
+  };
+}
+async function registerDevice(token, orgId, apiUrl) {
+  const res = await fetch(`${apiUrl}/v1/sync/devices/register`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      "x-headways-org-id": orgId
+    },
+    body: JSON.stringify({
+      publicKey: Buffer.from(`stub-pubkey-${Date.now()}`).toString("base64url"),
+      platform: process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux",
+      hostname: (await import("os")).hostname()
+    })
+  });
+  if (!res.ok) throw new Error(`Device registration failed: ${res.status}`);
+  const data = await res.json();
+  return { device_id: data.deviceId, device_token: data.deviceToken };
+}
+async function pollCatalog(state, apiUrl) {
+  const url = state.etag ? `${apiUrl}/v1/sync/catalog?since=${encodeURIComponent(state.etag)}` : `${apiUrl}/v1/sync/catalog`;
+  const res = await fetch(url, { headers: deviceHeaders(state) });
+  if (res.status === 304) return null;
+  if (!res.ok) throw new Error(`Catalog poll failed: ${res.status}`);
+  return res.json();
+}
+async function downloadAndMaterialize(slug, version, state, apiUrl) {
+  const res = await fetch(`${apiUrl}/v1/sync/bundles/${slug}/${version}`, {
+    redirect: "follow",
+    headers: deviceHeaders(state)
+  });
+  if (!res.ok) throw new Error(`Bundle fetch failed: ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  const skillsDir = join5(homedir2(), ".claude", "skills");
+  const dest = join5(skillsDir, slug);
+  const staging = join5(skillsDir, `.${slug}-staging`);
+  mkdirSync(staging, { recursive: true });
+  await extractTarGz(buf, staging);
+  if (existsSync(dest)) rmSync(dest, { recursive: true });
+  renameSync(staging, dest);
+  mkdirSync(INSTALLED_DIR, { recursive: true });
+  writeFileSync(
+    join5(INSTALLED_DIR, `${slug}.json`),
+    JSON.stringify(
+      { slug, version, runtime: "claude-code", installed_at: (/* @__PURE__ */ new Date()).toISOString() },
+      null,
+      2
+    )
+  );
+  console.log(`Materialized ${slug}@${version} \u2192 ${dest}`);
+}
+async function extractTarGz(buf, destDir) {
+  const decompressed = await new Promise((resolve, reject) => {
+    const chunks = [];
+    const gunzip = createGunzip();
+    const src = Readable.from(buf);
+    src.pipe(gunzip);
+    gunzip.on("data", (chunk) => chunks.push(chunk));
+    gunzip.on("end", () => resolve(Buffer.concat(chunks)));
+    gunzip.on("error", reject);
+  });
+  let offset = 0;
+  const { writeFileSync: wf, mkdirSync: md } = await import("fs");
+  const { dirname: dirname2 } = await import("path");
+  while (offset + 512 <= decompressed.length) {
+    const header = decompressed.slice(offset, offset + 512);
+    const name = header.slice(0, 100).toString("utf8").replace(/\0/g, "").trim();
+    if (!name) break;
+    const sizeOctal = header.slice(124, 136).toString("utf8").replace(/\0/g, "").trim();
+    const size = parseInt(sizeOctal, 8) || 0;
+    const typeFlag = header[156];
+    offset += 512;
+    if (typeFlag === 53 || name.endsWith("/")) {
+      md(join5(destDir, name), { recursive: true });
+    } else if (typeFlag === 0 || typeFlag === 48 || typeFlag === void 0) {
+      const filePath = join5(destDir, name);
+      md(dirname2(filePath), { recursive: true });
+      wf(filePath, decompressed.slice(offset, offset + size));
+    }
+    offset += Math.ceil(size / 512) * 512;
+  }
+}
+function registerSyncCommands(program2) {
+  const sync = program2.command("sync").description("Sync skills from Headways to local Claude Code");
+  sync.command("start").description("Register device and pull latest skill catalog from Headways").option("--daemon", "Run as background daemon (60s poll loop)").action(async (opts) => {
+    const cfg = readConfig();
+    if (!cfg.token || !cfg.orgId) {
+      console.error("Not logged in. Run: headways login");
+      process.exit(1);
+    }
+    const apiUrl = getApiUrl();
+    let state = readSyncState();
+    if (!state.device_id || !state.device_token) {
+      console.log("Registering device with Headways\u2026");
+      try {
+        const deviceState = await registerDevice(cfg.token, cfg.orgId, apiUrl);
+        state = { ...state, ...deviceState };
+        writeSyncState(state);
+        console.log(`Device registered: ${state.device_id}`);
+      } catch (err) {
+        console.error(`Registration failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+    }
+    const doPoll = async () => {
+      try {
+        const delta = await pollCatalog(state, apiUrl);
+        if (!delta) {
+          console.log("Catalog up to date.");
+          return;
+        }
+        state.etag = delta.etag;
+        state.last_poll = (/* @__PURE__ */ new Date()).toISOString();
+        writeSyncState(state);
+        const pendingMap = new Map(readPending().map((p) => [p.slug, p]));
+        for (const ev of delta.events) {
+          if (ev.kind === "version_published") {
+            if (ev.channel === "auto") {
+              console.log(`Auto-installing: ${ev.skill_slug}@${ev.version}`);
+              await downloadAndMaterialize(ev.skill_slug, ev.version, state, apiUrl);
+              pendingMap.delete(ev.skill_slug);
+            } else {
+              pendingMap.set(ev.skill_slug, {
+                slug: ev.skill_slug,
+                version: ev.version,
+                user_visible_change: ev.user_visible_change,
+                channel: ev.channel,
+                capabilities_delta_empty: ev.capabilities_delta_empty
+              });
+              console.log(
+                `Queued: ${ev.skill_slug}@${ev.version}${ev.user_visible_change ? ` \u2014 ${ev.user_visible_change}` : ""}`
+              );
+            }
+          } else if (ev.kind === "skill_archived" || ev.kind === "entitlement_revoked") {
+            pendingMap.delete(ev.skill_slug);
+            console.log(`Removed: ${ev.skill_slug}`);
+          }
+        }
+        writePending([...pendingMap.values()]);
+        console.log(`Synced. ETag: ${delta.etag}`);
+      } catch (err) {
+        console.error(`Poll error: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    };
+    await doPoll();
+    if (opts.daemon) {
+      console.log("Running sync daemon (60s interval). Press Ctrl-C to stop.");
+      setInterval(doPoll, 6e4);
+    }
+  });
+  sync.command("status").description("Show current sync status and pending updates").action(() => {
+    const state = readSyncState();
+    const pending = readPending();
+    if (!state.device_id) {
+      console.log("Device not registered. Run: headways sync start");
+      return;
+    }
+    console.log(`Device ID  : ${state.device_id}`);
+    console.log(`Last poll  : ${state.last_poll ?? "never"}`);
+    console.log(`Catalog ETag: ${state.etag ?? "none"}`);
+    if (pending.length === 0) {
+      console.log("\nAll skills up to date. No pending updates.");
+    } else {
+      console.log(`
+Pending updates (${pending.length}):`);
+      for (const p of pending) {
+        const change = p.user_visible_change ? ` \u2014 ${p.user_visible_change}` : "";
+        const caps = p.capabilities_delta_empty ? "" : " [CAPS CHANGED]";
+        console.log(`  ${p.slug}@${p.version}${change}${caps}`);
+      }
+      console.log("\nRun `headways accept <skill>` to install.");
+    }
+  });
+  program2.command("accept <skill>").description("Accept a pending skill update and materialize it locally").action(async (skillSlug) => {
+    const cfg = readConfig();
+    if (!cfg.token || !cfg.orgId) {
+      console.error("Not logged in. Run: headways login");
+      process.exit(1);
+    }
+    const pending = readPending();
+    const update = pending.find((p) => p.slug === skillSlug);
+    if (!update) {
+      console.error(`No pending update for skill: ${skillSlug}`);
+      console.log("Run `headways sync status` to see pending updates.");
+      process.exit(1);
+    }
+    const state = readSyncState();
+    if (!state.device_id || !state.device_token) {
+      console.error("Device not registered. Run: headways sync start");
+      process.exit(1);
+    }
+    console.log(`Accepting ${skillSlug}@${update.version}\u2026`);
+    await downloadAndMaterialize(skillSlug, update.version, state, getApiUrl());
+    writePending(pending.filter((p) => p.slug !== skillSlug));
+    console.log(
+      `${skillSlug} is ready \u2014 invoke it in Claude Code with the skill's invocation phrase.`
+    );
+  });
+}
+
+// src/commands/feedback.ts
+import "commander";
+function registerFeedbackCommand(program2) {
+  program2.command("feedback <skillSlug>").description("Submit feedback about a skill (posts to Headways API)").option(
+    "--reaction <type>",
+    "Reaction type: thumbs_up, thumbs_down, wrong_output, missing_step",
+    "thumbs_down"
+  ).option("--note <text>", "Free-text note about the issue").option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").action(
+    async (skillSlug, opts) => {
+      const cfg = readConfig();
+      if (!cfg.token) {
+        console.error("Not authenticated. Run `headways auth login` first.");
+        process.exit(1);
+      }
+      const runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
+      try {
+        await rawRequest(`/v1/skills/${skillSlug}/feedback?source=runtime_cli`, cfg.token, {
+          method: "POST",
+          body: JSON.stringify({ reaction: opts.reaction, note: opts.note, runId })
+        });
+        console.log(`Feedback submitted for ${skillSlug}.`);
+      } catch (err) {
+        console.error(`Error: ${String(err)}`);
+        process.exit(1);
+      }
+    }
+  );
+}
+
+// src/sdk/emit.ts
+import "commander";
+function registerEmitCommand(program2) {
+  program2.command("emit").description("Emit a skill run event (used by Claude Code hooks)").option("--run-id <runId>", "Skill run ID (or set HEADWAYS_RUN_ID env var)").option("--hook <hookName>", "Hook name to emit").option("--event <event>", "Legacy alias for --hook").option("--status <status>", "Tool result status (true=error, false=ok)").option("-f, --field <entries...>", "Field values in key=value format").allowUnknownOption(true).action(
+    async (opts) => {
+      const cfg = readConfig();
+      if (!cfg.token) return;
+      const runId = opts.runId ?? process.env["HEADWAYS_RUN_ID"];
+      if (!runId) return;
+      const hookName = opts.hook ?? opts.event ?? "tool.unknown";
+      const payload = {};
+      if (opts.status !== void 0) {
+        payload["tool_result_is_error"] = opts.status === "true" || opts.status === "1";
+      }
+      for (const entry of opts.field ?? []) {
+        const eqIdx = entry.indexOf("=");
+        if (eqIdx > 0) {
+          const k = entry.slice(0, eqIdx);
+          const v = entry.slice(eqIdx + 1);
+          payload[k] = v;
+        }
+      }
+      const apiUrl = getApiUrl();
+      try {
+        await fetch(`${apiUrl}/v1/skill-runs/${runId}/events`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${cfg.token}`
+          },
+          body: JSON.stringify({
+            events: [{ hookName, payload, ts: Date.now() }]
+          })
+        });
+      } catch {
+      }
+    }
+  );
+}
+
+// src/index.ts
+program.name("headways").description("Headways CLI \u2014 skill authoring, sync, and runtime SDK").version("0.1.0");
+registerAuthCommands(program);
+registerSkillsCommands(program);
+registerSyncCommands(program);
+registerFeedbackCommand(program);
+registerEmitCommand(program);
+program.parse();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@headways/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Headways CLI — authoring, sync, and runtime SDK",
+  "files": ["dist", "README.md"],
+  "bin": {
+    "headways": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@headways/db": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.15.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.7",
+    "node-fetch": "^3.3.2",
+    "yaml": "^2.5.1",
+    "zod": "^3.25.28"
+  },
+  "devDependencies": {
+    "@headways/config": "workspace:*",
+    "@types/node": "^22.16.5",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}