@sweny-ai/core 0.1.77 → 0.1.79

package/dist/cli/publish.js

@@ -14,7 +14,7 @@ import chalk from "chalk";
 import { parse as parseYaml } from "yaml";
 import { parseWorkflow, validateWorkflow } from "../schema.js";
 import { builtinSkills } from "../skills/index.js";
-import { discoverSkills } from "../skills/custom-loader.js";
+import { discoverSkillsWithDiagnostics } from "../skills/custom-loader.js";
 // ── Types ──────────────────────────────────────────────────────────────
 const VALID_CATEGORIES = ["triage", "security", "devops", "code-review", "testing", "content", "ops"];
 const VALID_SKILL_ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
@@ -35,8 +35,12 @@ export function validateWorkflowFile(filePath) {
     }
     try {
         const workflow = parseWorkflow(parsed);
-        // Build known skill IDs from builtins + custom + inline workflow skills
-        const customSkills = discoverSkills();
+        // Build known skill IDs from builtins + custom + inline workflow skills.
+        // Surface skill-loader diagnostics (malformed frontmatter, invalid ids,
+        // duplicate overrides) so publishers don't ship broken dependencies.
+        const { skills: customSkills, warnings: skillWarnings } = discoverSkillsWithDiagnostics();
+        for (const w of skillWarnings)
+            warnings.push(w.message);
         const allSkillIds = new Set([...builtinSkills.map((s) => s.id), ...customSkills.map((s) => s.id)]);
         // Inline skills defined in the workflow's skills block (a Record<id, def>) are also valid
         if (workflow.skills) {
@@ -343,12 +347,7 @@ async function openGitHubPR(type, id, sourcePath, meta) {
         }
         else {
             const destDir = path.join(tmpDir, "skills", "community", id);
-            fs.mkdirSync(destDir, { recursive: true });
-            // Copy entire skill directory
-            const files = fs.readdirSync(sourcePath);
-            for (const file of files) {
-                fs.copyFileSync(path.join(sourcePath, file), path.join(destDir, file));
-            }
+            copySkillDir(sourcePath, destDir);
             execFileSync("git", ["-C", tmpDir, "add", `skills/community/${id}`], { stdio: "pipe" });
         }
         s.message("Pushing...");
@@ -396,16 +395,25 @@ async function saveLocally(type, id, sourcePath) {
     }
     else {
         const destDir = path.join(outputDir, id);
-        fs.mkdirSync(destDir, { recursive: true });
-        const files = fs.readdirSync(sourcePath);
-        for (const file of files) {
-            fs.copyFileSync(path.join(sourcePath, file), path.join(destDir, file));
-        }
+        copySkillDir(sourcePath, destDir);
         p.log.success(`Saved to ${chalk.cyan(destDir)}`);
         p.log.info(`Submit manually: copy to skills/community/ in a fork of swenyai/marketplace`);
         return { type, id, name: id, outputPath: destDir };
     }
 }
+/**
+ * Recursively copy a skill source directory to its destination (Fix #17).
+ *
+ * Previously a flat `fs.readdirSync` + `fs.copyFileSync` loop: skills with
+ * nested directories (scripts/, references/, assets/) either silently
+ * shipped incomplete or — more often — threw EISDIR on the first subdir.
+ *
+ * Exported for tests; node:fs cp's recursive mode preserves structure.
+ */
+export function copySkillDir(sourceDir, destDir) {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.cpSync(sourceDir, destDir, { recursive: true });
+}
 // ── Command registration ───────────────────────────────────────────────
 export function registerPublishCommand(program) {
     program

package/dist/loader.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Workflow loader — read, parse, validate.
+ *
+ * The canonical path for CLI flows that read a workflow off disk. Composes
+ * file I/O + YAML/JSON parse + Zod schema parse + structural validation and
+ * returns a single tagged result so callers can render errors uniformly.
+ *
+ * Use this instead of calling `parseWorkflow` / `validateWorkflow` directly
+ * so the three user-facing surfaces (`sweny workflow run`, `sweny workflow
+ * validate`, `sweny publish`) agree on what "valid" means.
+ */
+import type { Workflow } from "./types.js";
+import { type WorkflowError } from "./schema.js";
+/** Structural/schema error. `code` is present only for structural errors. */
+export interface LoaderError {
+    message: string;
+    code?: WorkflowError["code"] | "IO" | "PARSE" | "SCHEMA";
+    nodeId?: string;
+}
+export type LoaderResult = {
+    ok: true;
+    workflow: Workflow;
+} | {
+    ok: false;
+    errors: LoaderError[];
+};
+export interface LoaderOptions {
+    /** Optional set of known skill IDs for UNKNOWN_SKILL validation. */
+    knownSkills?: Set<string>;
+}
+/**
+ * Load a workflow YAML or JSON file, parse with the canonical Zod schema,
+ * and run structural validation. All three phases contribute to `errors`.
+ */
+export declare function loadAndValidateWorkflow(filePath: string, options?: LoaderOptions): LoaderResult;
+/**
+ * Validate an already-parsed workflow object (e.g. from a marketplace fetch
+ * or Studio import). Same schema + structural passes as the file loader.
+ */
+export declare function validateParsed(raw: unknown, options?: LoaderOptions): LoaderResult;

package/dist/loader.js

@@ -0,0 +1,73 @@
+/**
+ * Workflow loader — read, parse, validate.
+ *
+ * The canonical path for CLI flows that read a workflow off disk. Composes
+ * file I/O + YAML/JSON parse + Zod schema parse + structural validation and
+ * returns a single tagged result so callers can render errors uniformly.
+ *
+ * Use this instead of calling `parseWorkflow` / `validateWorkflow` directly
+ * so the three user-facing surfaces (`sweny workflow run`, `sweny workflow
+ * validate`, `sweny publish`) agree on what "valid" means.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { ZodError } from "zod";
+import { workflowZ, validateWorkflow } from "./schema.js";
+/**
+ * Load a workflow YAML or JSON file, parse with the canonical Zod schema,
+ * and run structural validation. All three phases contribute to `errors`.
+ */
+export function loadAndValidateWorkflow(filePath, options = {}) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, errors: [{ message: `Could not read "${filePath}": ${msg}`, code: "IO" }] };
+    }
+    let raw;
+    try {
+        const ext = path.extname(filePath).toLowerCase();
+        raw = ext === ".yaml" || ext === ".yml" ? parseYaml(content) : JSON.parse(content);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, errors: [{ message: `Could not parse "${filePath}": ${msg}`, code: "PARSE" }] };
+    }
+    return validateParsed(raw, options);
+}
+/**
+ * Validate an already-parsed workflow object (e.g. from a marketplace fetch
+ * or Studio import). Same schema + structural passes as the file loader.
+ */
+export function validateParsed(raw, options = {}) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        const kind = raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw;
+        return { ok: false, errors: [{ message: `Expected a workflow object, got ${kind}`, code: "SCHEMA" }] };
+    }
+    let parsed;
+    try {
+        parsed = workflowZ.parse(raw);
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            const errors = err.issues.map((iss) => ({
+                message: `${iss.path.length > 0 ? iss.path.join(".") + ": " : ""}${iss.message}`,
+                code: "SCHEMA",
+            }));
+            return { ok: false, errors };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, errors: [{ message: msg, code: "SCHEMA" }] };
+    }
+    const structural = validateWorkflow(parsed, options.knownSkills);
+    if (structural.length > 0) {
+        return {
+            ok: false,
+            errors: structural.map((e) => ({ message: e.message, code: e.code, nodeId: e.nodeId })),
+        };
+    }
+    return { ok: true, workflow: parsed };
+}

package/dist/mcp-catalog.d.ts

@@ -0,0 +1,47 @@
+/**
+ * MCP Provider Catalog — single source of truth for provider/MCP wiring.
+ *
+ * Before this catalog existed, `buildSkillMcpServers` (skill-driven) and
+ * `buildAutoMcpServers` (flag-driven, legacy triage/implement) each encoded
+ * the same transport/auth/env for every provider. Drift was inevitable.
+ *
+ * Each entry declares:
+ *   - which trigger paths (skill id, provider flag, workspace tool) wire it
+ *   - how to build the McpServerConfig from credentials
+ *   - whether the server uses stdio or http transport
+ *   - if stdio: why the `npx -y` policy exception is acceptable (Fix #18)
+ *
+ * Adding a provider is a one-place edit. A module-load assertion and a
+ * test enforce that every stdio entry declares its exception reason.
+ */
+import type { McpServerConfig } from "./types.js";
+export interface McpCatalogEntry {
+    /** Canonical server id. Used as the key in the returned `Record<string, McpServerConfig>`. */
+    id: string;
+    /** Which trigger paths wire this server. Most entries match both skill-driven and flag-driven paths. */
+    triggers: {
+        /** Skill IDs that should wire this server (skill-driven path). */
+        skill?: string[];
+        /** Matching values for `sourceControlProvider` (flag-driven path). */
+        sourceControl?: string[];
+        /** Matching values for `issueTrackerProvider` (flag-driven path). */
+        issueTracker?: string[];
+        /** Matching entries in `observabilityProviders` (flag-driven path). */
+        observability?: string[];
+        /** Matching entries in `workspaceTools` (flag-driven path). */
+        workspaceTool?: string[];
+    };
+    /** Build the MCP server config from creds. Returns undefined if required creds are missing. */
+    wire: (creds: Record<string, string>) => McpServerConfig | undefined;
+    /** Transport family. Informational + policy enforcement (Fix #18). */
+    transport: "http" | "stdio";
+    /**
+     * For stdio servers, why `npx -y` is allowed. Null forbids the exception.
+     * Http servers must set this to null (no exception needed).
+     *
+     * ARCHITECTURE.md documents the acceptable reasons (official first-party
+     * vendor server with no public HTTP endpoint, etc.).
+     */
+    npxExceptionReason: string | null;
+}
+export declare const MCP_CATALOG: readonly McpCatalogEntry[];

package/dist/mcp-catalog.js

@@ -0,0 +1,304 @@
+/**
+ * MCP Provider Catalog — single source of truth for provider/MCP wiring.
+ *
+ * Before this catalog existed, `buildSkillMcpServers` (skill-driven) and
+ * `buildAutoMcpServers` (flag-driven, legacy triage/implement) each encoded
+ * the same transport/auth/env for every provider. Drift was inevitable.
+ *
+ * Each entry declares:
+ *   - which trigger paths (skill id, provider flag, workspace tool) wire it
+ *   - how to build the McpServerConfig from credentials
+ *   - whether the server uses stdio or http transport
+ *   - if stdio: why the `npx -y` policy exception is acceptable (Fix #18)
+ *
+ * Adding a provider is a one-place edit. A module-load assertion and a
+ * test enforce that every stdio entry declares its exception reason.
+ */
+// ── Catalog entries ─────────────────────────────────────────────────
+const github = {
+    id: "github",
+    triggers: {
+        skill: ["github"],
+        sourceControl: ["github"],
+        issueTracker: ["github-issues"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @modelcontextprotocol/server-github; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        if (!creds.GITHUB_TOKEN)
+            return undefined;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@modelcontextprotocol/server-github@latest"],
+            env: { GITHUB_PERSONAL_ACCESS_TOKEN: creds.GITHUB_TOKEN },
+        };
+    },
+};
+const gitlab = {
+    id: "gitlab",
+    triggers: {
+        skill: ["gitlab"],
+        sourceControl: ["gitlab"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @modelcontextprotocol/server-gitlab; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        if (!creds.GITLAB_TOKEN)
+            return undefined;
+        const env = { GITLAB_PERSONAL_ACCESS_TOKEN: creds.GITLAB_TOKEN };
+        const baseUrl = creds.GITLAB_URL || "https://gitlab.com";
+        if (baseUrl !== "https://gitlab.com")
+            env.GITLAB_API_URL = `${baseUrl}/api/v4`;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@modelcontextprotocol/server-gitlab@latest"],
+            env,
+        };
+    },
+};
+const linear = {
+    id: "linear",
+    triggers: {
+        skill: ["linear"],
+        issueTracker: ["linear"],
+    },
+    transport: "http",
+    npxExceptionReason: null,
+    wire: (creds) => {
+        if (!creds.LINEAR_API_KEY)
+            return undefined;
+        return {
+            type: "http",
+            url: "https://mcp.linear.app/mcp",
+            headers: { Authorization: `Bearer ${creds.LINEAR_API_KEY}` },
+        };
+    },
+};
+const jira = {
+    id: "jira",
+    triggers: {
+        skill: ["jira"],
+        issueTracker: ["jira"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Atlassian has no first-party MCP server; @sooperset/mcp-atlassian is the de-facto community standard. Revisit if Atlassian ships one.",
+    wire: (creds) => {
+        if (!creds.JIRA_URL || !creds.JIRA_EMAIL || !creds.JIRA_API_TOKEN)
+            return undefined;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@sooperset/mcp-atlassian@latest"],
+            env: {
+                JIRA_URL: creds.JIRA_URL,
+                JIRA_EMAIL: creds.JIRA_EMAIL,
+                JIRA_API_TOKEN: creds.JIRA_API_TOKEN,
+            },
+        };
+    },
+};
+const datadog = {
+    id: "datadog",
+    triggers: {
+        skill: ["datadog"],
+        observability: ["datadog"],
+    },
+    transport: "http",
+    npxExceptionReason: null,
+    wire: (creds) => {
+        if (!creds.DD_API_KEY || !creds.DD_APP_KEY)
+            return undefined;
+        return {
+            type: "http",
+            url: "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp",
+            headers: { DD_API_KEY: creds.DD_API_KEY, DD_APPLICATION_KEY: creds.DD_APP_KEY },
+        };
+    },
+};
+const sentry = {
+    id: "sentry",
+    triggers: {
+        skill: ["sentry"],
+        observability: ["sentry"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @sentry/mcp-server; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        if (!creds.SENTRY_AUTH_TOKEN)
+            return undefined;
+        const env = { SENTRY_ACCESS_TOKEN: creds.SENTRY_AUTH_TOKEN };
+        const sentryUrl = creds.SENTRY_URL;
+        if (sentryUrl && sentryUrl !== "https://sentry.io") {
+            try {
+                env.SENTRY_HOST = new URL(sentryUrl).hostname;
+            }
+            catch {
+                // malformed URL — leave SENTRY_HOST unset, server defaults to sentry.io
+            }
+        }
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@sentry/mcp-server@latest"],
+            env,
+        };
+    },
+};
+const newrelic = {
+    id: "newrelic",
+    triggers: {
+        skill: ["newrelic"],
+        observability: ["newrelic"],
+    },
+    transport: "http",
+    npxExceptionReason: null,
+    wire: (creds) => {
+        if (!creds.NEW_RELIC_API_KEY)
+            return undefined;
+        const region = creds.NEW_RELIC_REGION;
+        const url = region === "eu" ? "https://mcp.eu.newrelic.com/mcp/" : "https://mcp.newrelic.com/mcp/";
+        return {
+            type: "http",
+            url,
+            headers: { "Api-Key": creds.NEW_RELIC_API_KEY },
+        };
+    },
+};
+const betterstack = {
+    id: "betterstack",
+    triggers: {
+        skill: ["betterstack"],
+        observability: ["betterstack"],
+    },
+    transport: "http",
+    npxExceptionReason: null,
+    wire: (creds) => {
+        const token = creds.BETTERSTACK_API_TOKEN || creds.BETTERSTACK_TELEMETRY_TOKEN || creds.BETTERSTACK_UPTIME_TOKEN;
+        if (!token)
+            return undefined;
+        return {
+            type: "http",
+            url: "https://mcp.betterstack.com",
+            headers: { Authorization: `Bearer ${token}` },
+        };
+    },
+};
+const slack = {
+    id: "slack",
+    triggers: {
+        skill: ["slack"],
+        workspaceTool: ["slack"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @modelcontextprotocol/server-slack; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        if (!creds.SLACK_BOT_TOKEN)
+            return undefined;
+        const env = { SLACK_BOT_TOKEN: creds.SLACK_BOT_TOKEN };
+        if (creds.SLACK_TEAM_ID)
+            env.SLACK_TEAM_ID = creds.SLACK_TEAM_ID;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@modelcontextprotocol/server-slack@latest"],
+            env,
+        };
+    },
+};
+const notion = {
+    id: "notion",
+    triggers: {
+        skill: ["notion"],
+        workspaceTool: ["notion"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @notionhq/notion-mcp-server; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        const token = creds.NOTION_TOKEN || creds.NOTION_API_KEY;
+        if (!token)
+            return undefined;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@notionhq/notion-mcp-server@latest"],
+            env: { NOTION_TOKEN: token },
+        };
+    },
+};
+const pagerduty = {
+    id: "pagerduty",
+    triggers: {
+        skill: ["pagerduty"],
+        workspaceTool: ["pagerduty"],
+    },
+    transport: "http",
+    npxExceptionReason: null,
+    wire: (creds) => {
+        if (!creds.PAGERDUTY_API_TOKEN)
+            return undefined;
+        return {
+            type: "http",
+            url: "https://mcp.pagerduty.com/mcp",
+            headers: { Authorization: `Token token=${creds.PAGERDUTY_API_TOKEN}` },
+        };
+    },
+};
+const monday = {
+    id: "monday",
+    triggers: {
+        skill: ["monday"],
+        workspaceTool: ["monday"],
+    },
+    transport: "stdio",
+    npxExceptionReason: "Official @mondaydotcomorg/monday-api-mcp; no public HTTP MCP endpoint.",
+    wire: (creds) => {
+        if (!creds.MONDAY_TOKEN)
+            return undefined;
+        return {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "@mondaydotcomorg/monday-api-mcp@latest"],
+            env: { MONDAY_TOKEN: creds.MONDAY_TOKEN },
+        };
+    },
+};
+// asana was removed in Fix #15 — absent from SUPPORTED_WORKSPACE_TOOLS for
+// some time, and the asana-mcp package is community-maintained without a
+// clear first-party alternative. Add back in a dedicated catalog entry if
+// there's demand and a policy-compliant server to wire.
+// ── Assembled catalog ────────────────────────────────────────────────
+export const MCP_CATALOG = [
+    github,
+    gitlab,
+    linear,
+    jira,
+    datadog,
+    sentry,
+    newrelic,
+    betterstack,
+    slack,
+    notion,
+    pagerduty,
+    monday,
+];
+// ── Policy enforcement ──────────────────────────────────────────────
+/**
+ * Assert the `npx -y` policy (Fix #18). Thrown at module load and also
+ * asserted by the test suite, so a stdio entry missing `npxExceptionReason`
+ * never reaches shipping.
+ */
+function assertNpxPolicyCompliant(entries) {
+    for (const entry of entries) {
+        if (entry.transport === "stdio" && entry.npxExceptionReason === null) {
+            throw new Error(`MCP catalog entry "${entry.id}" uses stdio transport but declares no npxExceptionReason. ` +
+                `Stdio entries must document why the npx -y exception is acceptable. See ARCHITECTURE.md.`);
+        }
+        if (entry.transport === "http" && entry.npxExceptionReason !== null) {
+            throw new Error(`MCP catalog entry "${entry.id}" uses http transport but declares an npxExceptionReason. ` +
+                `Only stdio entries need an exception reason; set it to null for http entries.`);
+        }
+    }
+}
+assertNpxPolicyCompliant(MCP_CATALOG);

package/dist/mcp.d.ts

@@ -12,16 +12,13 @@ export interface SkillMcpOptions {
 /**
  * Build MCP server configs for the skills a workflow references.
  *
- * For each skill ID in `referencedSkills`, look up its MCP wiring (if any)
- * and include it only when the required credentials are present in `credentials`.
+ * For each entry in MCP_CATALOG whose skill triggers intersect
+ * `referencedSkills`, wire its MCP if credentials are present. Skills with
+ * no MCP variant (e.g. `notification`, `supabase`) are silently skipped —
+ * their in-process tools are wired separately by the executor. Unknown
+ * skill IDs pass through; the engine's hard-fail validation handles them.
  *
- * Skills with no MCP variant (e.g. `notification`, `supabase`) are silently
- * skipped — their in-process tools are wired separately by the executor.
- *
- * Unknown skill IDs (not built-in, not in this MCP catalog) are silently
- * skipped here; the engine's hard-fail validation handles them upstream.
- *
- * User-supplied servers always win on key conflict.
+ * Inline skill-declared servers and user-supplied servers layer on top.
  */
 export declare function buildSkillMcpServers(opts: SkillMcpOptions): Record<string, McpServerConfig>;
 /**