@solidactions/cli 1.13.0 → 1.15.0

package/README.md

@@ -118,6 +118,24 @@ Use `solidactions <command> --help` for full flag details on any command.
 |---------|-----------|-------------|
 | `webhook list <project>` | `-e`, `--show-secrets` | List webhook URLs |
 
+### skill
+
+Manage agent skills on the crews SOP surface. `push` is an idempotent upsert (create, or update on name collision).
+
+| Command | Key Flags | Description |
+|---------|-----------|-------------|
+| `skill push <dir>` | `--role <name>`, `--dry-run`, `--json` | Push a skill folder, or a whole plugin dir — recursive: pushes every `skills/*/SKILL.md`, converts `commands/*.md` → skills, and ingests each skill's `references/`. `--role` scopes to a role instead of the shared library |
+| `skill list` | `--json`, `--limit <n>` | List skills in the library |
+| `skill view <name>` | `--json` | Show one skill |
+| `skill pull <name> [dest]` | `--json` | Fetch a skill to a local folder for editing (inverse of push) |
+| `skill delete <name>` | `--json` | Delete a skill (Admin only) |
+
+### role
+
+| Command | Key Flags | Description |
+|---------|-----------|-------------|
+| `role push <dir>` | `--dry-run`, `--json` | Push a role definition (create or update) |
+
 ### workspace
 
 | Command | Description |

package/dist/commands/docs-push.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * solidactions docs push <dir>
+ *
+ * Recursively uploads a local markdown tree into SA-Docs via the docs MCP
+ * server's `docs_vault bulk_create` tool, mirroring folder structure.
+ *
+ * Prints a report distinguishing fully-published docs from "properties pending"
+ * ones (docs whose frontmatter properties couldn't be validated yet).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docsPushWithConfig = docsPushWithConfig;
+exports.docsPush = docsPush;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+const CHUNK_SIZE = 50;
+/**
+ * Recursively walk `dir` and collect all *.md files.
+ * Returns a list of absolute paths.
+ */
+function walkMarkdownFiles(dir) {
+    const results = [];
+    const walk = (current) => {
+        for (const entry of fs_1.default.readdirSync(current, { withFileTypes: true })) {
+            const abs = path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                results.push(abs);
+            }
+        }
+    };
+    walk(dir);
+    return results;
+}
+/**
+ * Convert an absolute file path to a bulk_create item, relative to `rootDir`.
+ */
+function fileToItem(absPath, rootDir) {
+    const title = path_1.default.basename(absPath, '.md');
+    const body = fs_1.default.readFileSync(absPath, 'utf8');
+    const relDir = path_1.default.relative(rootDir, path_1.default.dirname(absPath));
+    // Use POSIX separators; omit if file is in the root dir
+    const relative_folder_path = relDir === '' ? undefined : relDir.split(path_1.default.sep).join('/');
+    const item = { title, body, _filePath: absPath };
+    if (relative_folder_path !== undefined) {
+        item.relative_folder_path = relative_folder_path;
+    }
+    return item;
+}
+/**
+ * Merge two BulkCreateSummary objects by summing all numeric fields.
+ */
+function mergeSummaries(a, b) {
+    const keys = [
+        'created', 'overwritten', 'skipped', 'renamed', 'errors', 'folders_created',
+        'planned_create', 'planned_overwrite', 'planned_skip', 'planned_rename',
+    ];
+    const result = {};
+    for (const key of keys) {
+        const aVal = a[key] ?? 0;
+        const bVal = b[key] ?? 0;
+        if (aVal !== 0 || bVal !== 0) {
+            result[key] = aVal + bVal;
+        }
+    }
+    return result;
+}
+/**
+ * Format the merged summary into human-readable totals line.
+ * Normal run: created/overwritten/skipped/renamed. Dry-run: planned_*.
+ */
+function formatSummaryLine(summary, dryRun) {
+    const parts = [];
+    if (dryRun) {
+        if (summary.planned_create)
+            parts.push(`${summary.planned_create} planned create`);
+        if (summary.planned_overwrite)
+            parts.push(`${summary.planned_overwrite} planned overwrite`);
+        if (summary.planned_skip)
+            parts.push(`${summary.planned_skip} planned skip`);
+        if (summary.planned_rename)
+            parts.push(`${summary.planned_rename} planned rename`);
+    }
+    else {
+        if (summary.created)
+            parts.push(`${summary.created} created`);
+        if (summary.overwritten)
+            parts.push(`${summary.overwritten} updated`);
+        if (summary.skipped)
+            parts.push(`${summary.skipped} skipped`);
+        if (summary.renamed)
+            parts.push(`${summary.renamed} renamed`);
+        if (summary.errors)
+            parts.push(`${summary.errors} errors`);
+    }
+    return parts.join(', ') || '0 docs';
+}
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ */
+async function docsPushWithConfig(dir, options, config) {
+    const absDir = path_1.default.resolve(dir);
+    if (!fs_1.default.existsSync(absDir) || !fs_1.default.statSync(absDir).isDirectory()) {
+        process.stderr.write(chalk_1.default.red(`error: "${dir}" is not a directory.\n`));
+        process.exit(1);
+    }
+    const allFiles = walkMarkdownFiles(absDir);
+    if (allFiles.length === 0) {
+        process.stderr.write(chalk_1.default.red(`error: no .md files found under "${dir}" — nothing to push.\n`));
+        process.exit(1);
+    }
+    const items = allFiles.map((f) => fileToItem(f, absDir));
+    // Chunk into groups of CHUNK_SIZE
+    const chunks = [];
+    for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+        chunks.push(items.slice(i, i + CHUNK_SIZE));
+    }
+    const onConflict = options.onConflict ?? 'skip';
+    const allResultRows = [];
+    let mergedSummary = {};
+    for (const chunk of chunks) {
+        const callArgs = {
+            action: 'bulk_create',
+            on_conflict: onConflict,
+            items: chunk.map(({ title, body, relative_folder_path }) => {
+                const item = { title, body };
+                if (relative_folder_path !== undefined) {
+                    item.relative_folder_path = relative_folder_path;
+                }
+                return item;
+            }),
+        };
+        if (options.type) {
+            callArgs.type = options.type;
+        }
+        if (options.dryRun) {
+            callArgs.dry_run = true;
+        }
+        let mcpResult;
+        try {
+            mcpResult = await (0, mcp_1.callDocsTool)(config, 'docs_vault', callArgs);
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+            process.exit(1);
+        }
+        if (!mcpResult.ok) {
+            const code = mcpResult.data?.code ?? 'unknown_error';
+            const message = mcpResult.data?.message ?? 'MCP returned an error with no message';
+            process.stderr.write(chalk_1.default.red(`error: ${code}: ${message}\n`));
+            process.exit(1);
+        }
+        const data = mcpResult.data;
+        const rows = data?.results ?? [];
+        const summary = data?.summary ?? {};
+        // Correlate rows back to source files using chunk index
+        for (const row of rows) {
+            const sourceFile = chunk[row.index]?._filePath ?? '(unknown)';
+            allResultRows.push({
+                ...row,
+                file: path_1.default.relative(absDir, sourceFile),
+            });
+        }
+        mergedSummary = mergeSummaries(mergedSummary, summary);
+    }
+    // Collect pending items (results that have property_validation)
+    const pendingItems = allResultRows
+        .filter((r) => r.property_validation != null)
+        .map((r) => ({
+        file: r.file,
+        missing: r.property_validation.missing ?? [],
+        invalid: r.property_validation.invalid ?? [],
+    }));
+    // --json: output single JSON object
+    if (options.json) {
+        console.log(JSON.stringify({
+            summary: mergedSummary,
+            pending: pendingItems,
+            results: allResultRows,
+        }));
+        process.exit(0);
+    }
+    // Human-readable output
+    const summaryLine = formatSummaryLine(mergedSummary, !!options.dryRun);
+    if (options.dryRun) {
+        console.log(chalk_1.default.cyan(`[dry-run preview] ${summaryLine}`));
+    }
+    else {
+        console.log(chalk_1.default.green(`done: ${summaryLine}`));
+    }
+    if (pendingItems.length > 0) {
+        console.log(chalk_1.default.yellow(`\nProperties pending (${pendingItems.length} doc${pendingItems.length === 1 ? '' : 's'}):`));
+        for (const item of pendingItems) {
+            console.log(chalk_1.default.yellow(`  ${item.file}`));
+            if (item.missing.length > 0) {
+                console.log(chalk_1.default.yellow(`    missing: ${item.missing.join(', ')}`));
+            }
+            for (const inv of item.invalid) {
+                console.log(chalk_1.default.yellow(`    invalid: ${inv.key} — ${inv.reason}`));
+            }
+        }
+    }
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function docsPush(dir, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await docsPushWithConfig(dir, options, config);
+}

package/dist/commands/run-list.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runs = runs;
+exports.summaryStatusLabel = summaryStatusLabel;
+exports.detailedOutcomeTag = detailedOutcomeTag;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
@@ -70,6 +72,32 @@ async function runs(projectName, options = {}) {
     }
 }
 // ─── Display modes ─────────────────────────────────────────────────────────
+/**
+ * Summary-table status label for a run. Recovered/degraded runs share SUCCESS's
+ * execution_status, so without this they'd be indistinguishable from a clean success in
+ * the summary view. Returns the label to display and whether it's an "attention" outcome
+ * (rendered yellow). Falls back to the raw status for servers that don't send `outcome`.
+ */
+function summaryStatusLabel(run) {
+    if (run.outcome === 'recovered')
+        return { label: 'recovered', attention: true };
+    if (run.outcome === 'degraded')
+        return { label: 'degraded', attention: true };
+    return { label: run.execution_status || run.status || '?', attention: false };
+}
+/**
+ * Detailed-view tag appended to a run header ('' when none). Prefers the API `outcome`;
+ * falls back to the local hasRunErrors heuristic for servers that don't send `outcome`.
+ */
+function detailedOutcomeTag(run) {
+    if (run.outcome === 'recovered')
+        return ' [RECOVERED]';
+    if (run.outcome === 'degraded')
+        return ' [DEGRADED]';
+    if (hasRunErrors(run) && isSuccessStatus(run.execution_status || run.status || ''))
+        return ' [DEGRADED]';
+    return '';
+}
 function displaySummaryTable(runsList, projectName) {
     const header = projectName ? `Recent runs for "${projectName}":` : 'Recent runs:';
     console.log(chalk_1.default.blue(header));
@@ -79,8 +107,8 @@ function displaySummaryTable(runsList, projectName) {
     for (const run of runsList) {
         const id = String(run.id || '?').padEnd(8);
         const workflow = truncate(run.workflow_name || '?', 24).padEnd(25);
-        const status = run.execution_status || run.status || '?';
-        const statusColor = getStatusColor(status);
+        const { label: status, attention } = summaryStatusLabel(run);
+        const statusColor = attention ? chalk_1.default.yellow : getStatusColor(status);
         const triggeredAt = run.triggered_at ? new Date(run.triggered_at).toLocaleString() : '-';
         const triggeredBy = run.triggered_by || '-';
         console.log(chalk_1.default.gray(id) +
@@ -99,9 +127,9 @@ function displayDetailedList(runsList, projectName) {
         const status = run.execution_status || run.status || '?';
         const statusColor = getStatusColor(status);
         const exitStr = run.exit_code !== null && run.exit_code !== undefined ? ` (exit ${run.exit_code})` : '';
-        const isSilentFailure = hasRunErrors(run) && isSuccessStatus(status);
         console.log('');
-        const silentTag = isSilentFailure ? chalk_1.default.yellow(' [DEGRADED]') : '';
+        const outcomeTag = detailedOutcomeTag(run);
+        const silentTag = outcomeTag ? chalk_1.default.yellow(outcomeTag) : '';
         console.log(chalk_1.default.bold(`  Run #${run.id}`) + chalk_1.default.gray(` — ${run.workflow_name || '?'} (${run.project_name || '?'})`) + silentTag);
         console.log(`    Status:    ${statusColor(status)}${chalk_1.default.gray(exitStr)}`);
         console.log(`    Trigger:   ${chalk_1.default.gray(run.triggered_by || '-')}`);

package/dist/index.js

@@ -38,6 +38,7 @@ const skill_list_1 = require("./commands/skill-list");
 const skill_view_1 = require("./commands/skill-view");
 const skill_delete_1 = require("./commands/skill-delete");
 const role_push_1 = require("./commands/role-push");
+const docs_push_1 = require("./commands/docs-push");
 const config_1 = require("./utils/config");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
@@ -454,6 +455,21 @@ role
     .action(async (dir, options) => {
     await (0, role_push_1.rolePush)(dir, options);
 });
+// =============================================================================
+// docs <subcommand>  (SA-Docs surface)
+// =============================================================================
+const docs = program.command('docs').description('Manage docs in SA-Docs');
+docs
+    .command('push')
+    .description('Recursively upload a local markdown tree into SA-Docs')
+    .argument('<dir>', 'Path to the directory containing markdown files')
+    .option('--on-conflict <mode>', 'Conflict resolution: skip|overwrite|rename (default: skip)', 'skip')
+    .option('--type <slug>', 'Doc-type slug to apply to all uploaded docs')
+    .option('--dry-run', 'Preview what would be created without writing')
+    .option('--json', 'Output result as JSON')
+    .action(async (dir, options) => {
+    await (0, docs_push_1.docsPush)(dir, { onConflict: options.onConflict, type: options.type, dryRun: options.dryRun, json: options.json });
+});
 program.parseAsync().catch((err) => {
     console.error(chalk_1.default.red(err.message ?? String(err)));
     process.exit(1);

package/dist/utils/mcp.js

@@ -1,10 +1,10 @@
 "use strict";
 /**
- * Minimal MCP client for the SolidActions crews MCP server.
+ * Minimal MCP client for the SolidActions in-app MCP servers.
  *
  * Sends a single stateless JSON-RPC tools/call POST.  No initialize handshake
- * required — the streamable-HTTP transport at /mcp/crews accepts single
- * stateless POSTs (confirmed live).
+ * required — the streamable-HTTP transport accepts single stateless POSTs
+ * (confirmed live).
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -41,16 +41,17 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.callCrewsTool = callCrewsTool;
+exports.callDocsTool = callDocsTool;
 const http = __importStar(require("http"));
 const https = __importStar(require("https"));
 const url_1 = require("url");
 const api_1 = require("./api");
 /**
- * Call a single MCP tool on /mcp/crews.
+ * Internal: call a single MCP tool on the given endpoint path.
  *
  * Returns { ok: true, data: <success shape> } or { ok: false, data: { code, message } }.
  */
-async function callCrewsTool(config, toolName, args) {
+async function callMcpTool(config, endpointPath, toolName, args) {
     const baseHeaders = (0, api_1.getApiHeaders)(config, 'application/json');
     // Override Accept to include text/event-stream for streamable-HTTP transport
     const headers = {
@@ -66,7 +67,7 @@ async function callCrewsTool(config, toolName, args) {
             arguments: args,
         },
     });
-    const parsed = new url_1.URL(`${config.host}/mcp/crews`);
+    const parsed = new url_1.URL(`${config.host}${endpointPath}`);
     const isHttps = parsed.protocol === 'https:';
     const transport = isHttps ? https : http;
     const responseData = await new Promise((resolve, reject) => {
@@ -115,3 +116,15 @@ async function callCrewsTool(config, toolName, args) {
     }
     return { ok: !isError, data: toolData };
 }
+/**
+ * Call a single MCP tool on /mcp/crews.
+ */
+async function callCrewsTool(config, toolName, args) {
+    return callMcpTool(config, '/mcp/crews', toolName, args);
+}
+/**
+ * Call a single MCP tool on /mcp/docs.
+ */
+async function callDocsTool(config, toolName, args) {
+    return callMcpTool(config, '/mcp/docs', toolName, args);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidactions/cli",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "SolidActions CLI - Deploy and manage workflow automation",
   "main": "dist/index.js",
   "bin": {