@klhapp/skillmux 1.10.0 → 1.11.0

package/src/prompts.ts

@@ -1,4 +1,63 @@
 import { createInterface } from "node:readline/promises";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * Streams a prompt reads from and writes to. Injectable so prompts can be
+ * tested without a terminal; defaults to the real process streams.
+ */
+export interface PromptIO {
+  input?: Readable;
+  output?: Writable;
+}
+
+export const NO_INPUT_ERROR = "no input available on stdin; re-run with --yes";
+
+/**
+ * Asks one question and resolves with the raw answer.
+ *
+ * `isInteractive()` only inspects stdout, so a caller can legitimately reach a
+ * prompt while stdin is already at EOF (a pty'd stdout under CI, a wrapper
+ * process, `skillmux init < /dev/null`). A bare `readline.question()` never
+ * settles in that case and the CLI hangs forever, so the input stream ending
+ * before an answer arrives is turned into an actionable error instead.
+ *
+ * Piped answers (`printf 'y\n' | skillmux ...`) still work: `close` only wins
+ * the race when the stream ends with the question still outstanding.
+ */
+export async function askQuestion(query: string, io: PromptIO = {}): Promise<string> {
+  const readline = createInterface({
+    input: io.input ?? process.stdin,
+    output: io.output ?? process.stdout,
+  });
+  let settled = false;
+  try {
+    return await new Promise<string>((resolve, reject) => {
+      readline.question(query).then(
+        (answer) => {
+          settled = true;
+          resolve(answer);
+        },
+        (error) => {
+          settled = true;
+          reject(error);
+        },
+      );
+      // Fires on EOF, and also from the `finally` below. A piped stream ends
+      // immediately after delivering its answer, so `close` can arrive before
+      // the resolution microtask runs — deferring past pending microtasks lets
+      // a real answer win the race, leaving only a genuine EOF to reject.
+      readline.once("close", () => {
+        setImmediate(() => {
+          if (settled) return;
+          settled = true;
+          reject(new Error(NO_INPUT_ERROR));
+        });
+      });
+    });
+  } finally {
+    readline.close();
+  }
+}
 
 export interface SelectOption<T extends string> {
   value: T;
@@ -35,35 +94,31 @@ export function shouldUseWizard(
 export async function promptMultiSelect<T extends string>(
   question: string,
   options: readonly SelectOption<T>[],
+  io: PromptIO = {},
 ): Promise<T[]> {
-  console.log(`\n${question}`);
+  const output = io.output ?? process.stdout;
+  output.write(`\n${question}\n`);
   options.forEach((option, index) => {
     const checked = option.selected ? "x" : " ";
     const detail = option.detail ? `  ${option.detail}` : "";
-    console.log(`  ${index + 1}. [${checked}] ${option.label}${detail}`);
+    output.write(`  ${index + 1}. [${checked}] ${option.label}${detail}\n`);
   });
   const defaults = options
     .map((option, index) => option.selected ? String(index + 1) : "")
     .filter(Boolean)
     .join(",");
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaults ? ` [${defaults}]` : "";
-    const answer = await readline.question(`Select numbers, comma-separated${suffix}: `);
-    const selection = answer.trim() === "" && defaults ? defaults : answer;
-    return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
-  } finally {
-    readline.close();
-  }
+  const suffix = defaults ? ` [${defaults}]` : "";
+  const answer = await askQuestion(`Select numbers, comma-separated${suffix}: `, io);
+  const selection = answer.trim() === "" && defaults ? defaults : answer;
+  return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
 }
 
-export async function promptText(question: string, defaultValue = ""): Promise<string> {
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaultValue ? ` [${defaultValue}]` : "";
-    const answer = (await readline.question(`${question}${suffix}: `)).trim();
-    return answer || defaultValue;
-  } finally {
-    readline.close();
-  }
+export async function promptText(
+  question: string,
+  defaultValue = "",
+  io: PromptIO = {},
+): Promise<string> {
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  const answer = (await askQuestion(`${question}${suffix}: `, io)).trim();
+  return answer || defaultValue;
 }

package/src/scan.ts

@@ -156,7 +156,7 @@ export interface ScanResult {
   findings: ScanFinding[];
 }
 
-interface ScanContentTarget {
+interface ScanContentFile {
   skill_id: string;
   file: string;
   content: string;
@@ -177,21 +177,21 @@ export async function readTextFileOrNull(path: string): Promise<string | null> {
   }
 }
 
-async function collectSkillTargets(
+async function collectSkillFiles(
   vaultPath: string,
   skillId: string,
   skillMdBody: string,
-): Promise<ScanContentTarget[]> {
-  const targets: ScanContentTarget[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
+): Promise<ScanContentFile[]> {
+  const files: ScanContentFile[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
   for (const rel of listSupportingFiles(vaultPath, skillId)) {
     const content = await readTextFileOrNull(join(vaultPath, skillId, rel));
-    if (content !== null) targets.push({ skill_id: skillId, file: rel, content });
+    if (content !== null) files.push({ skill_id: skillId, file: rel, content });
   }
-  return targets;
+  return files;
 }
 
-interface ResolvedScanTargets {
-  targets: ScanContentTarget[];
+interface ResolvedScanFiles {
+  files: ScanContentFile[];
   /** skill_ids whose SKILL.md could not be parsed/decoded — must still be counted and
    *  flagged, never silently dropped, or a malformed SKILL.md becomes a scan-evasion trick. */
   unparseable: string[];
@@ -199,32 +199,32 @@ interface ResolvedScanTargets {
 
 /** Single-skill-dir mode when `rootPath` itself holds a SKILL.md; otherwise treats
  *  `rootPath` as a vault root and enumerates every skill dir under it. */
-async function resolveScanTargets(rootPath: string): Promise<ResolvedScanTargets> {
+async function resolveScanFiles(rootPath: string): Promise<ResolvedScanFiles> {
   if (existsSync(join(rootPath, "SKILL.md"))) {
     const skillId = basename(rootPath);
     const vaultPath = dirname(rootPath);
     const body = await readTextFileOrNull(join(rootPath, "SKILL.md"));
-    if (body === null) return { targets: [], unparseable: [skillId] };
-    return { targets: await collectSkillTargets(vaultPath, skillId, body), unparseable: [] };
+    if (body === null) return { files: [], unparseable: [skillId] };
+    return { files: await collectSkillFiles(vaultPath, skillId, body), unparseable: [] };
   }
 
   const unparseable: string[] = [];
   const skills = await scanVault(rootPath, (skillId) => unparseable.push(skillId));
-  const targets: ScanContentTarget[] = [];
+  const files: ScanContentFile[] = [];
   for (const skill of skills) {
-    targets.push(...(await collectSkillTargets(rootPath, skill.skill_id, skill.body)));
+    files.push(...(await collectSkillFiles(rootPath, skill.skill_id, skill.body)));
   }
-  return { targets, unparseable };
+  return { files, unparseable };
 }
 
 export async function scanPath(rootPath: string): Promise<ScanResult> {
-  const { targets, unparseable } = await resolveScanTargets(rootPath);
+  const { files, unparseable } = await resolveScanFiles(rootPath);
   const findings: ScanFinding[] = [];
   const skillIds = new Set<string>();
-  for (const target of targets) {
-    skillIds.add(target.skill_id);
-    for (const match of scanContent(target.content)) {
-      findings.push({ ...match, skill_id: target.skill_id, file: target.file });
+  for (const file of files) {
+    skillIds.add(file.skill_id);
+    for (const match of scanContent(file.content)) {
+      findings.push({ ...match, skill_id: file.skill_id, file: file.file });
     }
   }
   for (const skillId of unparseable) {

package/src/server.ts

@@ -668,7 +668,7 @@ export async function startServer(opts?: {
               const auditChanges: AdminAuditChange[] = [];
               for (const [k, v] of Object.entries(body.changes ?? {})) {
                 lastResult = await setDottedKey(k, String(v), {
-                  targetName: "remote",
+                  contextName: "remote",
                 });
                 auditChanges.push({
                   key: k,

package/src/init-clients.ts

@@ -1,220 +0,0 @@
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export const SUPPORTED_CLIENT_IDS = [
-  "claude-code",
-  "codex",
-  "gemini-cli",
-  "opencode",
-  "github-copilot",
-  "windsurf",
-  "antigravity",
-  "goose",
-  "hermes",
-  "skillmux-mcp",
-] as const;
-
-export type ClientId = (typeof SUPPORTED_CLIENT_IDS)[number];
-export type DeliveryMode = "managed-pins" | "full-vault" | "mcp";
-
-export interface DetectedClient {
-  client: ClientId;
-  evidence: string;
-}
-
-interface ClientDefinition {
-  id: ClientId;
-  surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
-  deliveryMode: DeliveryMode;
-}
-
-export interface PlannedClientSurface {
-  id: string;
-  targetName: string;
-  path: string;
-  deliveryMode: "managed-pins";
-  clients: ClientId[];
-}
-
-export interface ClientSurfacePlan {
-  clients: ClientDefinition[];
-  surfaces: PlannedClientSurface[];
-}
-
-type ReadinessStatus = "ready" | "planned" | "manual" | "not-applicable";
-
-export interface ReadinessAxis {
-  status: ReadinessStatus;
-  detail: string;
-}
-
-export interface ClientReadiness {
-  client: ClientId;
-  skillSurface: ReadinessAxis;
-  mcpRegistration: ReadinessAxis;
-  instructionSetup: ReadinessAxis;
-}
-
-export interface ResolvedBuiltInTarget {
-  targetName: string;
-  path: string;
-  warning?: string;
-}
-
-const CLIENTS: Record<ClientId, ClientDefinition> = {
-  "claude-code": { id: "claude-code", surfaceId: "claude-code", deliveryMode: "managed-pins" },
-  codex: { id: "codex", surfaceId: "codex", deliveryMode: "managed-pins" },
-  "gemini-cli": { id: "gemini-cli", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  opencode: { id: "opencode", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  "github-copilot": { id: "github-copilot", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  windsurf: { id: "windsurf", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
-  antigravity: { id: "antigravity", surfaceId: "antigravity", deliveryMode: "managed-pins" },
-  goose: { id: "goose", deliveryMode: "full-vault" },
-  hermes: { id: "hermes", deliveryMode: "full-vault" },
-  "skillmux-mcp": { id: "skillmux-mcp", deliveryMode: "mcp" },
-};
-
-export function detectInstalledClients(
-  options: {
-    home?: string;
-    codexHome?: string;
-    exists?: (path: string) => boolean;
-  } = {},
-): DetectedClient[] {
-  const home = options.home ?? homedir();
-  const codexHome = options.codexHome ?? join(home, ".codex");
-  const exists = options.exists ?? existsSync;
-  const candidates: Array<[ClientId, string]> = [
-    ["claude-code", join(home, ".claude")],
-    ["codex", codexHome],
-    ["gemini-cli", join(home, ".gemini")],
-    ["opencode", join(home, ".config", "opencode")],
-    ["github-copilot", join(home, ".config", "github-copilot")],
-    ["windsurf", join(home, ".codeium", "windsurf")],
-    ["goose", join(home, ".config", "goose")],
-    ["hermes", join(home, ".hermes")],
-  ];
-  return candidates
-    .filter(([, evidence]) => exists(evidence))
-    .map(([client, evidence]) => ({ client, evidence }));
-}
-
-function surfacePath(
-  surfaceId: NonNullable<ClientDefinition["surfaceId"]>,
-  options: { home: string; codexHome?: string },
-): string {
-  if (surfaceId === "agent-skills") return join(options.home, ".agents", "skills");
-  if (surfaceId === "claude-code") return join(options.home, ".claude", "skills");
-  if (surfaceId === "codex") return join(options.codexHome ?? join(options.home, ".codex"), "skills");
-  return join(options.home, ".gemini", "config", "skills");
-}
-
-export function resolveBuiltInTarget(
-  name: string,
-  options: { home?: string; codexHome?: string; customPath?: string } = {},
-): ResolvedBuiltInTarget {
-  const home = options.home ?? homedir();
-  if (name === "custom") {
-    if (!options.customPath) throw new Error("--target custom requires --path <dir>");
-    return { targetName: name, path: options.customPath };
-  }
-  if (name === "agent-skills" || name === "agents") {
-    return {
-      targetName: name,
-      path: surfacePath("agent-skills", { home }),
-      ...(name === "agents"
-        ? { warning: "--target agents is deprecated; use --target agent-skills" }
-        : {}),
-    };
-  }
-  if (name === "claude-code" || name === "claude") {
-    return {
-      targetName: name,
-      path: surfacePath("claude-code", { home }),
-      ...(name === "claude"
-        ? { warning: "--target claude is deprecated; use --target claude-code" }
-        : {}),
-    };
-  }
-  if (name === "codex") {
-    return {
-      targetName: name,
-      path: surfacePath("codex", { home, codexHome: options.codexHome }),
-    };
-  }
-  throw new Error(
-    `unknown --target "${name}"; supported targets: agent-skills, claude-code, codex, custom`,
-  );
-}
-
-export function planClientSurfaces(
-  requestedClients: readonly string[],
-  options: { home?: string; codexHome?: string } = {},
-): ClientSurfacePlan {
-  const clients = [...new Set(requestedClients)].map((id) => {
-    if (!SUPPORTED_CLIENT_IDS.includes(id as ClientId)) {
-      throw new Error(
-        `unsupported client "${id}"; supported clients: ${SUPPORTED_CLIENT_IDS.join(", ")}`,
-      );
-    }
-    return CLIENTS[id as ClientId];
-  });
-  const home = options.home ?? homedir();
-  const surfaces = new Map<string, PlannedClientSurface>();
-
-  for (const client of clients) {
-    if (!client.surfaceId) continue;
-    const path = surfacePath(client.surfaceId, { home, codexHome: options.codexHome });
-    const existing = surfaces.get(path);
-    if (existing) {
-      if (!existing.clients.includes(client.id)) existing.clients.push(client.id);
-      continue;
-    }
-    surfaces.set(path, {
-      id: client.surfaceId,
-      targetName: client.surfaceId,
-      path,
-      deliveryMode: "managed-pins",
-      clients: [client.id],
-    });
-  }
-
-  return { clients, surfaces: [...surfaces.values()] };
-}
-
-export function assessClientReadiness(
-  plan: ClientSurfacePlan,
-  instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {},
-): ClientReadiness[] {
-  return plan.clients.map((client) => {
-    const surface = plan.surfaces.find((candidate) => candidate.clients.includes(client.id));
-    let skillSurface: ReadinessAxis;
-    if (surface) {
-      skillSurface = { status: "planned", detail: surface.path };
-    } else if (client.id === "goose") {
-      skillSurface = { status: "manual", detail: "configure the full vault in Goose" };
-    } else if (client.id === "hermes") {
-      skillSurface = { status: "manual", detail: "configure the full vault in Hermes external_dirs" };
-    } else {
-      skillSurface = {
-        status: "not-applicable",
-        detail: "skills resolve through Skillmux MCP",
-      };
-    }
-
-    const mcpRegistration: ReadinessAxis = client.deliveryMode === "mcp"
-      ? { status: "manual", detail: "register the Skillmux MCP server" }
-      : { status: "not-applicable", detail: "native skill loading" };
-
-    return {
-      client: client.id,
-      skillSurface,
-      mcpRegistration,
-      instructionSetup: instructionReadiness[client.id] ?? {
-        status: "manual",
-        detail: "instruction adapter not applied",
-      },
-    };
-  });
-}