@solidactions/cli 1.10.3 → 1.12.0

package/dist/commands/dev.js

@@ -1,49 +1,385 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectSlug = resolveProjectSlug;
+exports.runDev = runDev;
 exports.dev = dev;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
-const dotenv_1 = __importDefault(require("dotenv"));
-async function dev(file, options) {
-    // Resolve the workflow file path
-    const filePath = path_1.default.resolve(file);
-    if (!fs_1.default.existsSync(filePath)) {
-        console.error(chalk_1.default.red(`File not found: ${filePath}`));
-        process.exit(1);
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const crypto_1 = require("crypto");
+const module_1 = require("module");
+/**
+ * Resolve the SA project slug for a workflow entry file and a target env.
+ *
+ * Walks up from the entry file to the project root (the directory containing
+ * `solidactions.yaml`), reads the declared `project:` name, and applies the
+ * SAME env→slug rule used by `deploy`: production keeps the bare name, every
+ * other environment appends `-<env>` (e.g. `sdk-test` → `sdk-test-dev`).
+ *
+ * Throws when the project root or the `project:` field cannot be found, so the
+ * caller surfaces a clear error instead of fetching against a bogus slug.
+ */
+function resolveProjectSlug(entryPath, env) {
+    const root = findSolidActionsRoot(path_1.default.resolve(entryPath));
+    if (!root) {
+        throw new Error(`could not find solidactions.yaml in any parent of ${entryPath}`);
     }
-    // Find the project root (directory containing package.json)
-    const projectDir = findProjectRoot(filePath);
-    if (!projectDir) {
-        console.error(chalk_1.default.red('Could not find package.json in parent directories.'));
-        process.exit(1);
+    const configPath = path_1.default.join(root, 'solidactions.yaml');
+    const config = js_yaml_1.default.load(fs_1.default.readFileSync(configPath, 'utf8'));
+    const projectName = config?.project;
+    if (!projectName || typeof projectName !== 'string') {
+        throw new Error(`solidactions.yaml at ${configPath} is missing a top-level "project:" name`);
     }
-    // Check that @solidactions/sdk is installed
-    const sdkPath = path_1.default.join(projectDir, 'node_modules', '@solidactions', 'sdk');
-    if (!fs_1.default.existsSync(sdkPath)) {
-        console.error(chalk_1.default.red('@solidactions/sdk is not installed in this project.'));
-        console.log(chalk_1.default.gray('Run: npm install @solidactions/sdk'));
-        process.exit(1);
+    return env === 'production' ? projectName : `${projectName}-${env}`;
+}
+/**
+ * Walk up from a starting path looking for the directory that holds
+ * `solidactions.yaml` (the project root). Returns null if none is found.
+ */
+function findSolidActionsRoot(startPath) {
+    let dir = fs_1.default.existsSync(startPath) && fs_1.default.statSync(startPath).isDirectory()
+        ? startPath
+        : path_1.default.dirname(startPath);
+    for (let i = 0; i < 10; i++) {
+        if (fs_1.default.existsSync(path_1.default.join(dir, 'solidactions.yaml'))) {
+            return dir;
+        }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
     }
-    // Check that the testing export exists
-    const testingPath = path_1.default.join(sdkPath, 'dist', 'src', 'testing');
-    if (!fs_1.default.existsSync(testingPath)) {
-        console.error(chalk_1.default.red('@solidactions/sdk version does not include testing utilities.'));
-        console.log(chalk_1.default.gray('Update to the latest SDK version: npm install @solidactions/sdk@latest'));
-        process.exit(1);
+    return null;
+}
+/**
+ * Run a workflow entry file in local-dev mode:
+ *   1. Fetch declared vars + connections from the platform (via api seam).
+ *   2. Apply any varsOverride, warning when a key shadows a platform var.
+ *   3. Spin up an SDK mock backend (createMockServer) for durable-primitive support.
+ *   4. import() the workflow module to populate the registry.
+ *   5. invoke() the first registered workflow descriptor.
+ *   6. Return { stdout, stderr, result }.
+ *
+ * Never calls process.exit; never lets exceptions escape (returns failed result).
+ */
+async function runDev(opts) {
+    const stdoutLines = [];
+    const stderrLines = [];
+    function out(msg) {
+        stdoutLines.push(msg);
+    }
+    function err(msg) {
+        stderrLines.push(msg);
+    }
+    // 1. Determine the API client (only when an env was requested). With no
+    //    --env, we run fully locally: NO platform fetch, ctx.vars starts empty.
+    let apiClient;
+    if (opts.env) {
+        if (opts.api) {
+            apiClient = opts.api;
+        }
+        else {
+            // Production path: build from CLI config.
+            // Lazy-import to keep tests fast (no config resolution needed).
+            const { requireConfigWithWorkspace } = await Promise.resolve().then(() => __importStar(require('../utils/api')));
+            const { getApiHeaders } = await Promise.resolve().then(() => __importStar(require('../utils/api')));
+            const axios = (await Promise.resolve().then(() => __importStar(require('axios')))).default;
+            const config = await requireConfigWithWorkspace();
+            // Real project resolution: read the project name from the workflow
+            // file's solidactions.yaml and apply the deploy env→slug rule.
+            const projectSlug = resolveProjectSlug(opts.entry, opts.env);
+            apiClient = {
+                projectSlug,
+                async fetchVarsAndConnections(_env) {
+                    const response = await axios.get(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings?resolve_oauth=true`, { headers: getApiHeaders(config) });
+                    return response.data || [];
+                },
+            };
+        }
+    }
+    // 2. Fetch vars from platform (only when an env + client are present).
+    let platformVars = [];
+    if (apiClient && opts.env) {
+        try {
+            platformVars = await apiClient.fetchVarsAndConnections(opts.env);
+        }
+        catch (e) {
+            err(`failed to fetch platform vars: ${e?.message ?? e}`);
+        }
+    }
+    // 3. Build ctx.vars from platform vars. A declared mapping is only readable
+    //    on ctx.vars when it is an OAuth connection (with proxy fields) OR has a
+    //    non-null resolved_value. Mappings with no value in this env are DROPPED
+    //    — and must NOT be counted in the summary (BUG #1).
+    const vars = {};
+    let connectionCount = 0;
+    let droppedCount = 0;
+    for (const pv of platformVars) {
+        if (pv.source_type === 'oauth_connection' && pv.proxy_url && pv.proxy_token && pv.connection_key) {
+            vars[pv.env_name] = {
+                key: pv.connection_key,
+                proxyUrl: pv.proxy_url,
+                proxyToken: pv.proxy_token,
+            };
+            connectionCount++;
+        }
+        else if (pv.resolved_value != null) {
+            vars[pv.env_name] = pv.resolved_value;
+        }
+        else {
+            droppedCount++;
+        }
+    }
+    // 4. Apply overrides, warning on shadows.
+    if (opts.varsOverride) {
+        for (const [key, value] of Object.entries(opts.varsOverride)) {
+            if (key in vars) {
+                err(`override shadows platform var: ${key}`);
+            }
+            vars[key] = value;
+        }
+    }
+    // 5. Print summary line. Report what is ACTUALLY readable on ctx.vars — the
+    //    plain-var count is the number of plain vars actually placed in `vars`
+    //    (total keys minus connection entries), never the raw mapping count.
+    if (opts.env) {
+        const plainVarCount = Object.keys(vars).length - connectionCount;
+        let summary = `Loaded ${plainVarCount} vars + ${connectionCount} connections from ${apiClient.projectSlug} / env ${opts.env}`;
+        if (droppedCount > 0) {
+            summary += ` (${droppedCount} declared ${droppedCount === 1 ? 'var' : 'vars'} had no value in this env and ${droppedCount === 1 ? 'was' : 'were'} skipped)`;
+        }
+        out(summary);
+    }
+    else {
+        out('Loaded 0 platform vars (no --env) — running locally');
+    }
+    // 6. Spin up SDK mock backend.
+    // Require createMockServer from the SDK's testing subpath.
+    //
+    // CRITICAL: root the require at the ENTRY FILE, not at __filename. The
+    // workflow module's own `import '@solidactions/sdk'` resolves the SDK
+    // relative to the entry file's project (e.g. examples/sdk-test/sdk), and
+    // it registers its workflow into THAT copy's registry singleton. If we
+    // resolved the SDK from the CLI's own node_modules instead (a different,
+    // npm-linked copy), we'd read an empty registry. Resolving from the entry's
+    // directory guarantees we hit the same SDK instance the workflow used.
+    const entryPath = path_1.default.resolve(opts.entry);
+    const _require = (0, module_1.createRequire)(entryPath);
+    // Resolve via the installed (or linked) @solidactions/sdk package.
+    const sdkTestingMain = _require.resolve('@solidactions/sdk/testing');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const { createMockServer } = _require(sdkTestingMain);
+    const mockServer = await createMockServer();
+    try {
+        // 7. Import the workflow entry file. Prefer the module's default export
+        //    (a WorkflowDescriptor returned by defineWorkflow) so that repeated
+        //    runDev() calls in the same test process don't need to clear and
+        //    re-register from a cached module (cached CJS modules don't re-run
+        //    their top-level code). If no default export, fall back to the registry.
+        const mod = await Promise.resolve(`${entryPath}`).then(s => __importStar(require(s)));
+        let descriptor;
+        if (mod?.default && typeof mod.default?.run === 'function') {
+            // Module exported a WorkflowDescriptor as its default — use it directly.
+            descriptor = mod.default;
+        }
+        else {
+            // Fall back: read from the SDK registry (populated by defineWorkflow side-effects).
+            const sdkMain = _require.resolve('@solidactions/sdk');
+            const registryPath = path_1.default.resolve(sdkMain, '..', 'invoke', 'registry.js');
+            const registry = _require(registryPath);
+            const all = registry.__getRegisteredWorkflows();
+            descriptor = all[0];
+        }
+        if (!descriptor) {
+            err('runDev: no workflows registered after importing the file.');
+            return {
+                stdout: stdoutLines.join('\n'),
+                stderr: stderrLines.join('\n'),
+                result: { status: 'failed', error: new Error('no workflow registered'), phase: 'run' },
+            };
+        }
+        // 8. Build InvokeCtx.
+        const runUuid = (0, crypto_1.randomUUID)();
+        const ctx = {
+            input: JSON.parse(opts.input || '{}'),
+            vars: Object.freeze(vars),
+            run: {
+                triggerId: 'local-dev',
+                runUuid,
+                runSecret: 'local-dev',
+                workerSessionId: (0, crypto_1.randomUUID)(),
+            },
+            app: {
+                appVersion: '0',
+                appId: 'local-dev',
+                tenantId: 'local-dev',
+            },
+            api: {
+                url: mockServer.baseUrl,
+                key: 'local-dev',
+            },
+            mode: 'local',
+        };
+        // 9. Create the run-row BEFORE invoking. invoke() itself never creates
+        //    the durable run record — the production launcher (SolidActions.run
+        //    → #initOneShotStatusRow) does that first, and step/sleep/recv
+        //    sub-routes (`/runs/status/<id>/...`) 404 ("Workflow not found")
+        //    against an absent row. A no-step workflow (the echo fixture) never
+        //    hits those routes so it survives without this; any workflow with a
+        //    runStep does not. Mirror #initOneShotStatusRow's CREATE shape.
+        const sdkMainForInvoke = _require.resolve('@solidactions/sdk');
+        const httpClientPath = path_1.default.resolve(sdkMainForInvoke, '..', 'http_client.js');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { HttpClient } = _require(httpClientPath);
+        try {
+            const client = new HttpClient({ baseUrl: ctx.api.url, apiKey: ctx.api.key });
+            await client.post('/runs/status', {
+                workflowUUID: ctx.run.runUuid,
+                status: 'PENDING',
+                workflowName: descriptor.name ?? '',
+                workflowClassName: '',
+                workflowConfigName: '',
+                output: null,
+                error: null,
+                authenticatedUser: '',
+                assumedRole: '',
+                authenticatedRoles: [],
+                request: {},
+                executorId: String(ctx.run.triggerId),
+                applicationVersion: ctx.app.appVersion,
+                applicationID: ctx.app.appId,
+                createdAt: Date.now(),
+                priority: 0,
+                ownerXid: (0, crypto_1.randomUUID)(),
+                options: {},
+            });
+        }
+        catch (e) {
+            // Best-effort, symmetric with #initOneShotStatusRow's swallow.
+            err(`failed to create local run-row: ${e?.message ?? e}`);
+        }
+        // 10. Invoke via internal SDK path (invoke() is not in the public index).
+        const invokePath = path_1.default.resolve(sdkMainForInvoke, '..', 'invoke', 'invoke.js');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { invoke } = _require(invokePath);
+        const result = await invoke(descriptor, ctx);
+        return {
+            stdout: stdoutLines.join('\n'),
+            stderr: stderrLines.join('\n'),
+            result,
+        };
+    }
+    finally {
+        await mockServer.stop();
     }
-    // Load .env file from project root
-    const envPath = path_1.default.join(projectDir, '.env');
-    if (fs_1.default.existsSync(envPath)) {
-        dotenv_1.default.config({ path: envPath });
-        console.log(chalk_1.default.gray(`Loaded .env from ${projectDir}`));
+}
+/**
+ * Env var set on the tsx re-exec child so it does NOT re-exec again. Without
+ * this guard the `--env` path would fork itself forever.
+ */
+const TSX_REEXEC_GUARD = 'SOLIDACTIONS_DEV_TSX_REEXEC';
+/**
+ * Detect whether the current Node process already has a TypeScript loader
+ * registered (tsx / ts-node). When true, `await import('<file>.ts')` works
+ * in-process and we can run `runDev` directly without re-exec.
+ */
+function hasTsLoader() {
+    if (process.env[TSX_REEXEC_GUARD] === '1') {
+        return true;
+    }
+    const execArgv = process.execArgv.join(' ');
+    return /tsx|ts-node/.test(execArgv) || Boolean(process._preload_modules);
+}
+/**
+ * Re-exec the CLI under `npx tsx` so that `runDev`'s `await import()` of a
+ * `.ts` workflow file resolves against tsx's TypeScript loader. The child runs
+ * the SAME command (`dev <file> [--env <env>] --input <json>`) with the re-exec
+ * guard set, so it falls straight through to {@link runDev}.
+ *
+ * tsx is resolved via `npx`; the child's cwd is the project root so its
+ * node_modules tsx is preferred. `env` is optional — when omitted the child
+ * runs the bare local path (no platform fetch, empty ctx.vars).
+ */
+function reexecUnderTsx(file, env, input, projectDir) {
+    // dist/src/commands/dev.js → CLI entry is dist/index.js (two dirs up).
+    const cliEntry = path_1.default.resolve(__dirname, '..', 'index.js');
+    const args = ['tsx', cliEntry, 'dev', file, '--input', input];
+    if (env) {
+        args.push('--env', env);
     }
-    // Validate input JSON if provided
+    const result = (0, child_process_1.spawnSync)('npx', args, {
+        stdio: 'inherit',
+        cwd: projectDir,
+        env: { ...process.env, [TSX_REEXEC_GUARD]: '1' },
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === 'ENOENT') {
+            console.error(chalk_1.default.red('npx not found. Make sure Node.js is installed.'));
+        }
+        else {
+            console.error(chalk_1.default.red(`Failed to start tsx loader: ${result.error.message}`));
+        }
+        return 1;
+    }
+    return result.status ?? 1;
+}
+/**
+ * Handler for `solidactions dev <file> [--env <env>]`: run the workflow LOCALLY
+ * through the in-process invoke() engine.
+ *
+ * With `--env`: pulls declared variable-mappings from the SA API and builds
+ * `ctx.vars` for the chosen environment. WITHOUT `--env`: NO platform fetch and
+ * `ctx.vars` starts empty `{}` — the host `process.env` is NEVER leaked into the
+ * workflow. Either way the workflow runs against the SDK mock backend via
+ * {@link runDev}. `.ts` entries are loaded by re-exec'ing under `npx tsx`.
+ */
+async function dev(file, options) {
+    const env = options.env;
     const input = options.input || '{}';
+    const filePath = path_1.default.resolve(file);
+    if (!fs_1.default.existsSync(filePath)) {
+        console.error(chalk_1.default.red(`File not found: ${filePath}`));
+        process.exit(1);
+    }
     try {
         JSON.parse(input);
     }
@@ -51,65 +387,55 @@ async function dev(file, options) {
         console.error(chalk_1.default.red('Invalid JSON input. Use -i \'{"key": "value"}\''));
         process.exit(1);
     }
-    // Write temp bootstrap file
-    const bootstrapPath = path_1.default.join(projectDir, '.solidactions-dev-bootstrap.mjs');
-    const bootstrapContent = generateBootstrap(filePath, input);
-    try {
-        fs_1.default.writeFileSync(bootstrapPath, bootstrapContent);
-        console.log(chalk_1.default.blue('SolidActions local dev mode'));
-        console.log(chalk_1.default.gray(`File:  ${path_1.default.relative(projectDir, filePath)}`));
-        console.log(chalk_1.default.gray(`Input: ${input}`));
-        console.log(chalk_1.default.gray('---'));
-        // Spawn npx tsx with the bootstrap file
-        const child = (0, child_process_1.spawn)('npx', ['tsx', bootstrapPath], {
-            stdio: 'inherit',
-            cwd: projectDir,
-        });
-        child.on('error', (err) => {
-            cleanup(bootstrapPath);
-            if (err.code === 'ENOENT') {
-                console.error(chalk_1.default.red('npx not found. Make sure Node.js is installed.'));
+    // .ts entry under plain node has no loader — re-exec under tsx, then return.
+    if (!hasTsLoader() && /\.(ts|tsx|mts|cts)$/.test(filePath)) {
+        const projectDir = findProjectRoot(filePath) ?? process.cwd();
+        // Surface a clear slug-resolution error here (before forking) rather
+        // than letting the child fail with an opaque exit code. Only relevant
+        // when an env was requested (bare runs do no platform fetch).
+        if (env) {
+            try {
+                resolveProjectSlug(filePath, env);
             }
-            else {
-                console.error(chalk_1.default.red(`Failed to start: ${err.message}`));
+            catch (err) {
+                console.error(chalk_1.default.red(`Failed: ${err.message}`));
+                process.exit(1);
             }
-            process.exit(1);
-        });
-        child.on('exit', (code) => {
-            cleanup(bootstrapPath);
-            process.exit(code ?? 1);
-        });
-        // Also clean up on signals
-        process.on('SIGINT', () => {
-            cleanup(bootstrapPath);
-            child.kill('SIGINT');
-        });
-        process.on('SIGTERM', () => {
-            cleanup(bootstrapPath);
-            child.kill('SIGTERM');
-        });
+        }
+        process.exit(reexecUnderTsx(file, env, input, projectDir));
+    }
+    // In-process path (already under a TS loader, or a .js/.mjs entry).
+    let result;
+    try {
+        result = await runDev({ entry: filePath, input, env });
     }
     catch (err) {
-        cleanup(bootstrapPath);
         console.error(chalk_1.default.red(`Failed: ${err.message}`));
         process.exit(1);
     }
-}
-function generateBootstrap(workflowFile, input) {
-    // Use forward slashes for the import path (works cross-platform in ESM)
-    const importPath = workflowFile.replace(/\\/g, '/');
-    return `// Auto-generated by solidactions dev - do not commit
-import { createMockServer } from '@solidactions/sdk/testing';
-
-const server = await createMockServer();
-
-process.env.SOLIDACTIONS_API_URL = server.baseUrl;
-process.env.SOLIDACTIONS_API_KEY = 'local-dev';
-process.env.WORKFLOW_INPUT = ${JSON.stringify(input)};
-
-// Import the workflow file - this triggers SolidActions.run() at module level
-await import(${JSON.stringify(importPath)});
-`;
+    if (result.stdout) {
+        console.log(result.stdout);
+    }
+    if (result.stderr) {
+        console.error(chalk_1.default.yellow(result.stderr));
+    }
+    const r = result.result;
+    if (r.status === 'completed') {
+        console.log(chalk_1.default.green('✓ completed'));
+        console.log(chalk_1.default.gray('Output:'), JSON.stringify(r.output));
+        process.exit(0);
+    }
+    if (r.status === 'suspended') {
+        console.log(chalk_1.default.yellow(`Workflow suspended: ${r.reason ?? 'unknown'}`));
+        process.exit(0);
+    }
+    if (r.status === 'cancelled') {
+        console.log(chalk_1.default.yellow('Workflow cancelled'));
+        process.exit(1);
+    }
+    // failed
+    console.error(chalk_1.default.red(`✗ failed (${r.phase ?? 'run'}):`), r.error?.message ?? String(r.error));
+    process.exit(1);
 }
 function findProjectRoot(startPath) {
     let dir = path_1.default.dirname(startPath);
@@ -124,13 +450,3 @@ function findProjectRoot(startPath) {
     }
     return null;
 }
-function cleanup(filePath) {
-    try {
-        if (fs_1.default.existsSync(filePath)) {
-            fs_1.default.unlinkSync(filePath);
-        }
-    }
-    catch {
-        // Ignore cleanup errors
-    }
-}

package/dist/commands/oauth-actions-show.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.oauthActionsShow = oauthActionsShow;
+exports.buildSnippet = buildSnippet;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
@@ -18,7 +19,7 @@ async function oauthActionsShow(platform, actionId, options) {
             process.stdout.write(JSON.stringify(action, null, 2) + '\n');
             return;
         }
-        renderHumanReadable(action);
+        renderHumanReadable(action, options);
     }
     catch (error) {
         if (error.response?.status === 404) {
@@ -36,7 +37,7 @@ async function oauthActionsShow(platform, actionId, options) {
         process.exit(1);
     }
 }
-function renderHumanReadable(action) {
+function renderHumanReadable(action, options) {
     const method = (action.method || 'GET').toUpperCase();
     const ioSchema = action.io_schema || {};
     const example = ioSchema.ioExample?.input;
@@ -73,15 +74,125 @@ function renderHumanReadable(action) {
         console.log('');
     }
     console.log(chalk_1.default.bold('Paste-ready snippet:'));
-    console.log(chalk_1.default.gray(indent(buildSnippet(action))));
+    if (options.legacyEnv) {
+        console.log(chalk_1.default.yellow('  (--legacy-env: deprecated form, will be removed in a future release)'));
+    }
+    console.log(chalk_1.default.gray(indent(buildSnippet(action, options.var, options.legacyEnv))));
+}
+/**
+ * Render a fetch() call against the SA proxy using the ctx.vars contract.
+ *
+ * The proxy requires:
+ *   - Authorization: Bearer <proxyToken>   (per-trigger scoped token from ctx.vars)
+ *   - X-OAuth-Connection-Key: <key>        (connection identifier from ctx.vars)
+ *   - X-OAuth-Action-Id: <action_id>       (the action being called)
+ *
+ * For modifier actions the body MUST include `connectionKey` alongside user params.
+ *
+ * Pass --var <NAME> to set the ctx.vars variable name (defaults to YOUR_CONNECTION).
+ * Pass --legacy-env to emit the old process.env form (deprecated, will be removed).
+ */
+function buildSnippet(action, varName, legacyEnv) {
+    if (legacyEnv) {
+        return buildLegacySnippet(action);
+    }
+    return buildCtxVarsSnippet(action, varName);
+}
+/**
+ * New ctx.vars-based snippet (the live proxy contract).
+ *
+ * proxyUrl  — the SA proxy base URL injected by the runtime at workflow start
+ * proxyToken — a per-trigger scoped Bearer token, NOT a long-lived secret
+ * key        — the connection key used by the proxy to look up the OAuth credentials
+ *
+ * Headers sent to the proxy:
+ *   Authorization: Bearer ${ctx.vars.<VAR>.proxyToken}
+ *   X-OAuth-Connection-Key: ${ctx.vars.<VAR>.key}
+ *   X-OAuth-Action-Id: '<action_id>'
+ *
+ * Do NOT include X-SA-Connection — that header is stripped by the proxy (STRIPPED_INBOUND).
+ */
+function buildCtxVarsSnippet(action, varName) {
+    const method = (action.method || 'GET').toUpperCase();
+    const platform = action.platform;
+    const varRef = varName || 'YOUR_CONNECTION';
+    const example = action.io_schema?.ioExample?.input;
+    const pathTemplate = (action.path || '').replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_m, name) => '${' + name.trim() + '}');
+    const queryEntries = example?.query ? Object.entries(example.query) : [];
+    const queryString = queryEntries.length
+        ? '?' + queryEntries.flatMap(([k, v]) => {
+            const encodedKey = encodeURIComponent(k);
+            const items = Array.isArray(v) ? v : [v];
+            return items.map((item) => `${encodedKey}=\${encodeURIComponent(${JSON.stringify(item)})}`);
+        }).join('&')
+        : '';
+    // Build the headers block: Authorization, X-OAuth-Connection-Key, X-OAuth-Action-Id,
+    // then any non-proxy-managed example headers, then Content-Type if body is present.
+    const proxyHeaderLines = [
+        `      'Authorization': \`Bearer \${ctx.vars.${varRef}.proxyToken}\`,`,
+        `      'X-OAuth-Connection-Key': ctx.vars.${varRef}.key,`,
+        `      'X-OAuth-Action-Id': ${JSON.stringify(action.action_id)},`,
+    ];
+    const exampleHeaders = example?.headers || {};
+    for (const [k, v] of Object.entries(exampleHeaders)) {
+        if (isProxyManagedHeader(k))
+            continue;
+        proxyHeaderLines.push(`      ${JSON.stringify(k)}: ${JSON.stringify(v)},`);
+    }
+    if (example?.body !== undefined && example.body !== null) {
+        const hasContentType = Object.keys(exampleHeaders).some(k => k.toLowerCase() === 'content-type');
+        if (!hasContentType) {
+            proxyHeaderLines.push(`      'Content-Type': 'application/json',`);
+        }
+    }
+    const headersBlock = proxyHeaderLines.join('\n');
+    const lines = [];
+    lines.push('const res = await fetch(');
+    lines.push(`  \`\${ctx.vars.${varRef}.proxyUrl}/${platform}${pathTemplate}${queryString}\`,`);
+    lines.push('  {');
+    lines.push(`    method: '${method}',`);
+    lines.push('    headers: {');
+    lines.push(headersBlock);
+    lines.push('    },');
+    if (example?.body !== undefined && example.body !== null) {
+        // Modifier actions: body already contains connectionKey from the API example.
+        // In the new contract the proxy uses X-OAuth-Connection-Key for routing, but
+        // modifier actions additionally require connectionKey IN the body so the
+        // upstream provider receives it. Substitute with a live ctx.vars reference.
+        const bodyObj = example.body;
+        const isModifier = typeof bodyObj === 'object' && bodyObj !== null && 'connectionKey' in bodyObj;
+        let bodyExpr;
+        if (isModifier) {
+            // Build the body object manually so we can emit `ctx.vars.<VAR>.key`
+            // (an unquoted JS expression) as the connectionKey value rather than
+            // a string literal.
+            const otherFields = Object.entries(bodyObj)
+                .filter(([k]) => k !== 'connectionKey')
+                .map(([k, v]) => `  ${JSON.stringify(k)}: ${JSON.stringify(v)}`)
+                .join(',\n');
+            const otherPart = otherFields ? `,\n${otherFields}` : '';
+            bodyExpr = `{\n  connectionKey: ctx.vars.${varRef}.key${otherPart}\n}`;
+        }
+        else {
+            bodyExpr = JSON.stringify(bodyObj, null, 2);
+        }
+        const bodyLines = bodyExpr
+            .split('\n')
+            .map((l, i) => (i === 0 ? l : '    ' + l))
+            .join('\n');
+        lines.push(`    body: JSON.stringify(${bodyLines}),`);
+    }
+    lines.push('  }');
+    lines.push(');');
+    lines.push('const data = await res.json();');
+    return lines.join('\n');
 }
 /**
- * Render a fetch() call against the SA proxy with `{{name}}` path placeholders
- * rewritten to `${name}` template-literal slots, query parameters appended,
- * and the example body inlined verbatim (so the AI substitutes values into the
- * known-good shape rather than inferring it from JSON Schema).
+ * Legacy process.env-based snippet (deprecated).
+ * Emitted only when --legacy-env is passed.
+ * This form no longer matches the live proxy contract — use the ctx.vars form.
  */
-function buildSnippet(action) {
+function buildLegacySnippet(action) {
     const method = (action.method || 'GET').toUpperCase();
     const platform = action.platform;
     const platformEnv = platform.toUpperCase().replace(/-/g, '_');
@@ -153,5 +264,8 @@ function isProxyManagedHeader(name) {
     const lower = name.toLowerCase();
     return lower === 'authorization'
         || lower.startsWith('x-pica-')
-        || lower.startsWith('x-one-');
+        || lower.startsWith('x-one-')
+        || lower === 'x-sa-connection'
+        || lower === 'x-oauth-connection-key'
+        || lower === 'x-oauth-action-id';
 }

package/dist/commands/skill-push.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * solidactions skill push <dir>
+ *
+ * Pushes a local skill folder into the crews library via the crews MCP server.
+ * Idempotent upsert: create, or update on name collision.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSkillFile = parseSkillFile;
+exports.readTopLevelReferences = readTopLevelReferences;
+exports.skillPushWithConfig = skillPushWithConfig;
+exports.skillPush = skillPush;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const api_1 = require("../utils/api");
+const mcp_1 = require("../utils/mcp");
+/**
+ * Parse a SKILL.md file that begins with a YAML frontmatter block.
+ *
+ * Returns { name, description, properties, body } where:
+ *   - name and description come from the frontmatter
+ *   - properties is the rest of the frontmatter (excluding name and description)
+ *   - body is everything after the closing --- delimiter
+ *
+ * Throws with a descriptive message if the file is malformed or missing
+ * required fields.
+ */
+function parseSkillFile(content) {
+    if (!content.startsWith('---')) {
+        throw new Error('SKILL.md must begin with a YAML frontmatter block (---).');
+    }
+    // Find the closing --- delimiter (must be on its own line after the opening ---)
+    const afterOpen = content.slice(3);
+    const closeIdx = afterOpen.indexOf('\n---');
+    if (closeIdx === -1) {
+        throw new Error('SKILL.md frontmatter is not closed (missing closing ---).');
+    }
+    const yamlBlock = afterOpen.slice(0, closeIdx);
+    // Body is everything after the closing ---\n
+    const body = afterOpen.slice(closeIdx + 4).replace(/^\n/, '');
+    let fm;
+    try {
+        fm = js_yaml_1.default.load(yamlBlock);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse SKILL.md frontmatter YAML: ${e.message}`);
+    }
+    if (!fm || typeof fm !== 'object') {
+        throw new Error('SKILL.md frontmatter is empty or not a YAML object.');
+    }
+    if (!fm.name || typeof fm.name !== 'string') {
+        throw new Error('SKILL.md frontmatter must contain a "name" field (string).');
+    }
+    if (!fm.description || typeof fm.description !== 'string') {
+        throw new Error('SKILL.md frontmatter must contain a "description" field (string).');
+    }
+    const { name, description, ...rest } = fm;
+    // Remove 'type' if present — the server sets it
+    const { type: _type, ...properties } = rest;
+    return { name, description, properties, body };
+}
+/**
+ * Read top-level (non-recursive) files in dir, excluding SKILL.md.
+ * Returns a map of filename → utf8 contents.
+ */
+function readTopLevelReferences(dir) {
+    const entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const references = {};
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (entry.name === 'SKILL.md')
+            continue;
+        const filePath = path_1.default.join(dir, entry.name);
+        references[entry.name] = fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    return references;
+}
+/**
+ * Core implementation — accepts an injected config so tests can point at a
+ * stub server without touching the filesystem config.
+ */
+async function skillPushWithConfig(dir, options, config) {
+    const absDir = path_1.default.resolve(dir);
+    // 1. Check directory exists
+    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);
+    }
+    // 2. Read SKILL.md
+    const skillMdPath = path_1.default.join(absDir, 'SKILL.md');
+    if (!fs_1.default.existsSync(skillMdPath)) {
+        process.stderr.write(chalk_1.default.red(`error: "${skillMdPath}" not found. The skill directory must contain a SKILL.md file.\n`));
+        process.exit(1);
+    }
+    const skillMdContent = fs_1.default.readFileSync(skillMdPath, 'utf8');
+    // 3. Parse frontmatter + body
+    let parsed;
+    try {
+        parsed = parseSkillFile(skillMdContent);
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
+        process.exit(1);
+    }
+    const { name, description, properties, body } = parsed;
+    // 4. Read sibling reference files
+    const references = readTopLevelReferences(absDir);
+    // 5. Compose an idempotent upsert: try create; on name_collision, edit.
+    const isRole = !!options.role;
+    const tool = isRole ? 'roles' : 'skills';
+    const createArgs = isRole
+        ? { action: 'create_skill', role: options.role, name, description, body, properties, references }
+        : { action: 'create', name, description, body, properties, references };
+    let result;
+    try {
+        result = await (0, mcp_1.callCrewsTool)(config, tool, createArgs);
+    }
+    catch (e) {
+        process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+        process.exit(1);
+    }
+    let didUpdate = false;
+    // 6. On name collision, switch to the edit path (the upsert). properties → properties_patch.
+    if (!result.ok && result.data?.code === 'name_collision') {
+        const editArgs = isRole
+            ? { action: 'edit_skill', role: options.role, name, description, body, properties_patch: properties, references }
+            : { action: 'edit', identifier: name, description, body, properties_patch: properties, references };
+        try {
+            result = await (0, mcp_1.callCrewsTool)(config, tool, editArgs);
+        }
+        catch (e) {
+            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+            process.exit(1);
+        }
+        didUpdate = true;
+    }
+    // 7. Handle result.
+    if (!result.ok) {
+        const errData = result.data;
+        const errCode = errData?.code ?? 'unknown_error';
+        const errMsg = errData?.message ?? 'MCP returned an error with no message';
+        process.stderr.write(chalk_1.default.red(`${errCode}: ${errMsg}\n`));
+        process.exit(1);
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result.data));
+        process.exit(0);
+    }
+    const data = result.data;
+    if (didUpdate) {
+        // edit shape: {version_id, body_blob_sha}
+        console.log(chalk_1.default.green(`updated skill '${name}' (version ${data.version_id ?? '?'})`));
+    }
+    else {
+        // create shape: {skill_doc_id, folder_id, reference_doc_ids}
+        const skillDocId = data.skill_doc_id ?? data.doc_id ?? data.id ?? '?';
+        const refCount = Object.keys(data.reference_doc_ids ?? {}).length;
+        console.log(chalk_1.default.green(`created skill '${name}' (doc ${skillDocId}, ${refCount} refs)`));
+    }
+    process.exit(0);
+}
+/**
+ * Entry point called from index.ts.
+ */
+async function skillPush(dir, options) {
+    const config = await (0, api_1.requireConfigWithWorkspace)();
+    await skillPushWithConfig(dir, options, config);
+}

package/dist/index.js

@@ -32,6 +32,7 @@ const oauth_actions_search_1 = require("./commands/oauth-actions-search");
 const oauth_actions_list_1 = require("./commands/oauth-actions-list");
 const oauth_actions_show_1 = require("./commands/oauth-actions-show");
 const workspaces_1 = require("./commands/workspaces");
+const skill_push_1 = require("./commands/skill-push");
 const config_1 = require("./utils/config");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
@@ -123,7 +124,11 @@ program
     .description('Run a workflow locally using an in-memory mock server (no deploy needed)')
     .argument('<file>', 'Workflow file to run (e.g., src/simple-steps.ts)')
     .option('-i, --input <json>', 'JSON input for the workflow', '{}')
+    .option('-e, --env <env>', 'Pull platform variables for this environment (e.g. dev, staging, production)')
     .action((file, options) => {
+    // Unified in-process invoke path. With --env: fetch declared vars, build
+    // ctx.vars, invoke locally. Without --env: NO platform fetch, ctx.vars is
+    // empty {} (the host process.env is never leaked into the workflow).
     (0, dev_1.dev)(file, options);
 });
 // =============================================================================
@@ -365,6 +370,8 @@ oauthActionsCmd
     .command('show <platform> <action-id>')
     .description('Show full schema, example body, and a paste-ready fetch snippet for one action')
     .option('--json', 'Emit raw JSON for AI/script consumption')
+    .option('--var <NAME>', 'ctx.vars variable name for the connection (default: YOUR_CONNECTION)')
+    .option('--legacy-env', 'Emit the deprecated process.env-based snippet (will be removed in a future release)')
     .action((platform, actionId, options) => {
     (0, oauth_actions_show_1.oauthActionsShow)(platform, actionId, options);
 });
@@ -385,6 +392,19 @@ ai
     .option('--all', 'Install all available examples')
     .option('--overwrite', 'Overwrite existing examples without warning')
     .action((names, options) => { (0, ai_examples_1.aiExamples)(names, options); });
+// =============================================================================
+// skill <subcommand>  (SOP surface — flat top-level noun per cli#34)
+// =============================================================================
+const skill = program.command('skill').description('Manage agent skills (crews SOP surface)');
+skill
+    .command('push')
+    .description('Push a local skill folder into the library (create, or update if it already exists)')
+    .argument('<dir>', 'Path to the skill directory (must contain SKILL.md)')
+    .option('--role <name>', 'Scope the skill to a role instead of the shared library')
+    .option('--json', 'Output result as JSON')
+    .action(async (dir, options) => {
+    await (0, skill_push_1.skillPush)(dir, options);
+});
 program.parseAsync().catch((err) => {
     console.error(chalk_1.default.red(err.message ?? String(err)));
     process.exit(1);

package/dist/utils/mcp.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Minimal MCP client for the SolidActions crews MCP server.
+ *
+ * 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).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callCrewsTool = callCrewsTool;
+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.
+ *
+ * Returns { ok: true, data: <success shape> } or { ok: false, data: { code, message } }.
+ */
+async function callCrewsTool(config, toolName, args) {
+    const baseHeaders = (0, api_1.getApiHeaders)(config, 'application/json');
+    // Override Accept to include text/event-stream for streamable-HTTP transport
+    const headers = {
+        ...baseHeaders,
+        'Accept': 'application/json, text/event-stream',
+    };
+    const body = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: {
+            name: toolName,
+            arguments: args,
+        },
+    });
+    const parsed = new url_1.URL(`${config.host}/mcp/crews`);
+    const isHttps = parsed.protocol === 'https:';
+    const transport = isHttps ? https : http;
+    const responseData = await new Promise((resolve, reject) => {
+        const options = {
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: parsed.pathname + (parsed.search || ''),
+            method: 'POST',
+            headers: {
+                ...headers,
+                'Content-Length': Buffer.byteLength(body),
+            },
+        };
+        const req = transport.request(options, (res) => {
+            let raw = '';
+            res.on('data', (chunk) => { raw += chunk; });
+            res.on('end', () => {
+                if (res.statusCode && res.statusCode >= 400) {
+                    reject(new Error(`MCP request failed with HTTP ${res.statusCode}: ${raw}`));
+                }
+                else {
+                    resolve(raw);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+    let parsed2;
+    try {
+        parsed2 = JSON.parse(responseData);
+    }
+    catch {
+        throw new Error(`MCP server returned non-JSON response: ${responseData}`);
+    }
+    const result = parsed2?.result;
+    const isError = result?.isError === true;
+    const textContent = result?.content?.[0]?.text ?? '{}';
+    let toolData;
+    try {
+        toolData = JSON.parse(textContent);
+    }
+    catch {
+        throw new Error(`MCP tool result content is not valid JSON: ${textContent}`);
+    }
+    return { ok: !isError, data: toolData };
+}

package/package.json

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