@solidactions/cli 0.4.1 → 0.6.0

package/README.md

@@ -36,6 +36,7 @@ solidactions deploy <project-name> <path>
 | `env:delete <key>` | Delete an environment variable |
 | `env:map <project> <key> <global-key>` | Map a global variable to a project |
 | `env:pull <project>` | Pull resolved env vars (including OAuth tokens) to a local file |
+| `env:push <project> [path]` | Push .env values to a project |
 | `schedule:set <project> <cron>` | Set a cron schedule for a workflow |
 | `schedule:list <project>` | List schedules for a project |
 | `schedule:delete <project> <id>` | Delete a schedule |

package/dist/commands/ai-examples.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiExamples = aiExamples;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const prompts_1 = __importDefault(require("prompts"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const github_1 = require("../utils/github");
+const markers_1 = require("../utils/markers");
+async function downloadDirectory(owner, repo, remotePath, localPath) {
+    const contents = await (0, github_1.listRepoContents)(owner, repo, remotePath);
+    fs_extra_1.default.ensureDirSync(localPath);
+    for (const item of contents) {
+        const localItemPath = path_1.default.join(localPath, item.name);
+        if (item.type === 'file') {
+            const content = await (0, github_1.fetchRawFile)(owner, repo, `${remotePath}/${item.name}`);
+            fs_1.default.writeFileSync(localItemPath, content, 'utf8');
+        }
+        else if (item.type === 'dir') {
+            await downloadDirectory(owner, repo, `${remotePath}/${item.name}`, localItemPath);
+        }
+    }
+}
+async function aiExamples(names, options = {}) {
+    try {
+        console.log(chalk_1.default.blue('Discovering available examples...'));
+        // Discover available examples
+        const repoContents = await (0, github_1.listRepoContents)('SolidActions', 'solidactions-examples');
+        const availableExamples = repoContents.filter((item) => item.type === 'dir' && !item.name.startsWith('.'));
+        if (availableExamples.length === 0) {
+            console.log(chalk_1.default.yellow('No examples found in the repository.'));
+            process.exit(0);
+        }
+        // Determine which to clone
+        let selected;
+        if (options.all) {
+            selected = availableExamples.map((e) => e.name);
+        }
+        else if (names.length > 0) {
+            const availableNames = availableExamples.map((e) => e.name);
+            for (const name of names) {
+                if (!availableNames.includes(name)) {
+                    console.error(chalk_1.default.red(`Example "${name}" not found. Available: ${availableNames.join(', ')}`));
+                    process.exit(1);
+                }
+            }
+            selected = names;
+        }
+        else {
+            const response = await (0, prompts_1.default)({
+                type: 'multiselect',
+                name: 'selected',
+                message: 'Select examples to install',
+                choices: availableExamples.map((e) => ({ title: e.name, value: e.name })),
+            });
+            if (!response.selected || response.selected.length === 0) {
+                console.log(chalk_1.default.yellow('No examples selected.'));
+                process.exit(0);
+            }
+            selected = response.selected;
+        }
+        // Clone each selected example
+        const examplesDir = '.solidactions/examples';
+        let installedCount = 0;
+        for (const name of selected) {
+            const localDir = path_1.default.join(examplesDir, name);
+            if (fs_1.default.existsSync(localDir) && !options.overwrite) {
+                console.log(chalk_1.default.yellow(`Example "${name}" already exists. Use --overwrite to replace.`));
+                continue;
+            }
+            if (fs_1.default.existsSync(localDir) && options.overwrite) {
+                fs_extra_1.default.removeSync(localDir);
+            }
+            console.log(chalk_1.default.gray(`Downloading ${name}...`));
+            await downloadDirectory('SolidActions', 'solidactions-examples', name, localDir);
+            console.log(chalk_1.default.green(`✓ Installed example: ${name}`));
+            installedCount++;
+        }
+        // Detect AI helper file and upsert examples reference
+        const aiHelperFile = (0, markers_1.findAiHelperFile)();
+        if (!aiHelperFile) {
+            console.log(chalk_1.default.yellow('No AI helper file found. Run "solidactions ai:init" first to create one.'));
+        }
+        else {
+            // List ALL installed examples (existing + newly installed)
+            const allInstalled = [];
+            if (fs_1.default.existsSync(examplesDir)) {
+                const dirs = fs_1.default.readdirSync(examplesDir, { withFileTypes: true });
+                for (const dir of dirs) {
+                    if (dir.isDirectory()) {
+                        allInstalled.push(dir.name);
+                    }
+                }
+            }
+            const examplesList = allInstalled.map((name) => `- ${name}`).join('\n');
+            const examplesNote = `## SolidActions Examples
+
+Example workflows are available in \`.solidactions/examples/\`. Use these as reference patterns when writing SolidActions workflows.
+
+Installed examples:
+${examplesList}
+
+When writing workflows, check these examples for patterns covering steps, sleep, signals, child workflows, retries, events, messaging, parallel execution, scheduling, OAuth, streaming, and webhooks.`;
+            (0, markers_1.upsertMarkerSection)(aiHelperFile, 'SolidActions Examples', examplesNote);
+        }
+        console.log(chalk_1.default.green(`✓ Installed ${installedCount} example(s) to .solidactions/examples/`));
+    }
+    catch (error) {
+        if (error.message?.includes('rate limit')) {
+            console.error(chalk_1.default.red(error.message));
+        }
+        else if (error.message?.includes('not found')) {
+            console.error(chalk_1.default.red(error.message));
+        }
+        else if (error.message?.includes('Failed to')) {
+            console.error(chalk_1.default.red('Network error: Could not reach GitHub. Check your internet connection.'));
+        }
+        else {
+            console.error(chalk_1.default.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/ai-init.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aiInit = aiInit;
+const fs_1 = __importDefault(require("fs"));
+const chalk_1 = __importDefault(require("chalk"));
+const prompts_1 = __importDefault(require("prompts"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const github_1 = require("../utils/github");
+const markers_1 = require("../utils/markers");
+async function aiInit(options = {}) {
+    try {
+        // Determine target file
+        let targetFile;
+        if (options.claude && options.agents) {
+            console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
+            process.exit(1);
+        }
+        if (options.claude) {
+            targetFile = 'CLAUDE.md';
+        }
+        else if (options.agents) {
+            targetFile = 'AGENTS.md';
+        }
+        else {
+            const response = await (0, prompts_1.default)({
+                type: 'select',
+                name: 'file',
+                message: 'Which AI helper file?',
+                choices: [
+                    { title: 'CLAUDE.md', value: 'CLAUDE.md' },
+                    { title: 'AGENTS.md', value: 'AGENTS.md' },
+                ],
+            });
+            if (!response.file) {
+                console.log(chalk_1.default.yellow('Cancelled.'));
+                process.exit(0);
+            }
+            targetFile = response.file;
+        }
+        console.log(chalk_1.default.blue('Fetching AI helper content...'));
+        // Fetch AI helper content from examples repo
+        const aiContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-examples', 'CLAUDE.md');
+        // Fetch SDK reference
+        const sdkContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-ts-sdk', 'docs/sdk-reference.md');
+        // Save SDK reference to .solidactions/sdk-reference.md
+        fs_extra_1.default.ensureDirSync('.solidactions');
+        fs_1.default.writeFileSync('.solidactions/sdk-reference.md', sdkContent, 'utf8');
+        console.log(chalk_1.default.green('✓ SDK reference saved to .solidactions/sdk-reference.md'));
+        // Upsert main AI helper section
+        (0, markers_1.upsertMarkerSection)(targetFile, 'SolidActions', aiContent);
+        // Upsert SDK reference pointer section
+        const sdkReferenceNote = `## SolidActions SDK Reference
+
+The full SDK API reference is available at \`.solidactions/sdk-reference.md\`. Refer to it for detailed function signatures, error classes, retry configuration, and advanced patterns like forking, streaming, and signal URLs.`;
+        (0, markers_1.upsertMarkerSection)(targetFile, 'SolidActions SDK Reference', sdkReferenceNote);
+        console.log(chalk_1.default.green(`✓ AI helper installed to ${targetFile}`));
+    }
+    catch (error) {
+        if (error.message?.includes('rate limit')) {
+            console.error(chalk_1.default.red(error.message));
+        }
+        else if (error.message?.includes('not found')) {
+            console.error(chalk_1.default.red(error.message));
+        }
+        else if (error.message?.includes('Failed to fetch')) {
+            console.error(chalk_1.default.red('Network error: Could not reach GitHub. Check your internet connection.'));
+        }
+        else {
+            console.error(chalk_1.default.red('Error:'), error.message);
+        }
+        process.exit(1);
+    }
+}

package/dist/commands/deploy.js

@@ -12,6 +12,7 @@ const form_data_1 = __importDefault(require("form-data"));
 const chalk_1 = __importDefault(require("chalk"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
 const init_1 = require("./init");
+const env_1 = require("../utils/env");
 /**
  * Validate project structure before deployment.
  * Checks for required files and SDK dependency.
@@ -84,94 +85,12 @@ function validateProject(sourceDir) {
     }
     return { valid: errors.length === 0, errors, warnings };
 }
-/**
- * Parse a .env file into a key-value map.
- */
-function parseEnvFile(filePath) {
-    const envMap = new Map();
-    if (!fs_1.default.existsSync(filePath)) {
-        return envMap;
-    }
-    const content = fs_1.default.readFileSync(filePath, 'utf8');
-    const lines = content.split('\n');
-    for (const line of lines) {
-        const trimmed = line.trim();
-        // Skip empty lines and comments
-        if (!trimmed || trimmed.startsWith('#')) {
-            continue;
-        }
-        const equalsIndex = trimmed.indexOf('=');
-        if (equalsIndex === -1) {
-            continue;
-        }
-        const key = trimmed.substring(0, equalsIndex).trim();
-        let value = trimmed.substring(equalsIndex + 1).trim();
-        // Remove surrounding quotes if present
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        }
-        envMap.set(key, value);
-    }
-    return envMap;
-}
-/**
- * Parse YAML env declarations into structured format.
- * Handles the new simplified format:
- *   - VAR_NAME           -> { key: "VAR_NAME", mappedTo: null }
- *   - VAR_NAME: GLOBAL   -> { key: "VAR_NAME", mappedTo: "GLOBAL" }
- */
-function parseYamlEnvVars(config) {
-    const parsedVars = [];
-    if (!config.env || !Array.isArray(config.env)) {
-        return parsedVars;
-    }
-    for (const item of config.env) {
-        if (typeof item === 'string') {
-            // Simple string: - VAR_NAME (declared only, needs configuration)
-            parsedVars.push({ key: item, mappedTo: null, oauthName: null });
-        }
-        else if (typeof item === 'object' && item !== null) {
-            // Object: - VAR_NAME: GLOBAL_NAME or - VAR_NAME: { oauth: connection-name }
-            const keys = Object.keys(item);
-            if (keys.length === 1) {
-                const key = keys[0];
-                const value = item[key];
-                if (typeof value === 'object' && value !== null && 'oauth' in value) {
-                    if (typeof value.oauth !== 'string' || !value.oauth) {
-                        throw new Error(`Invalid env config for ${key}: 'oauth' must be a non-empty string`);
-                    }
-                    parsedVars.push({ key, mappedTo: null, oauthName: value.oauth });
-                }
-                else {
-                    parsedVars.push({ key, mappedTo: value || null, oauthName: null });
-                }
-            }
-        }
-    }
-    return parsedVars;
-}
-/**
- * Extract declared variable keys from solidactions.yaml env config.
- * Returns a set of env var keys that are declared in YAML.
- */
-function getYamlDeclaredVars(config) {
-    const parsedVars = parseYamlEnvVars(config);
-    return new Set(parsedVars.map(v => v.key));
-}
-/**
- * Check if deployEnv is enabled in the config.
- * New format has deployEnv at top level.
- */
-function isDeployEnvEnabled(config) {
-    return config.deployEnv === true;
-}
 /**
  * Push YAML env declarations to the project.
  * This registers all YAML-declared vars and their mappings.
  */
 async function pushYamlDeclarations(host, apiKey, projectSlug, yamlConfig) {
-    const parsedVars = parseYamlEnvVars(yamlConfig);
+    const parsedVars = (0, env_1.parseYamlEnvVars)(yamlConfig);
     if (parsedVars.length === 0) {
         return;
     }
@@ -196,71 +115,6 @@ async function pushYamlDeclarations(host, apiKey, projectSlug, yamlConfig) {
         console.error(chalk_1.default.yellow('Warning: Failed to sync YAML declarations:'), error.response?.data?.message || error.message);
     }
 }
-/**
- * Push environment variables from .env file to project.
- * Only pushes vars that are declared in solidactions.yaml.
- */
-async function pushEnvVars(host, apiKey, projectSlug, sourceDir, environment, yamlConfig) {
-    // Get vars declared in YAML
-    const declaredVars = getYamlDeclaredVars(yamlConfig);
-    if (declaredVars.size === 0) {
-        console.log(chalk_1.default.gray('No environment variables declared in solidactions.yaml'));
-        return;
-    }
-    // Read the .env file for this environment
-    const envFileName = environment === 'production' ? '.env' : `.env.${environment}`;
-    const envFilePath = path_1.default.join(sourceDir, envFileName);
-    if (!fs_1.default.existsSync(envFilePath)) {
-        console.log(chalk_1.default.yellow(`⚠ ${envFileName} not found, skipping env push`));
-        // Warn about each missing declared var
-        for (const key of declaredVars) {
-            console.log(chalk_1.default.yellow(`  ⚠ ${key}: no value (not in ${envFileName})`));
-        }
-        return;
-    }
-    // Parse the .env file
-    const envValues = parseEnvFile(envFilePath);
-    // Filter to only YAML-declared vars
-    const variables = [];
-    const missing = [];
-    for (const key of declaredVars) {
-        const value = envValues.get(key);
-        if (value !== undefined) {
-            // Mark vars containing "secret", "key", "token", "password" as secrets
-            const isSecret = /secret|key|token|password|credential/i.test(key);
-            variables.push({ key, value, is_secret: isSecret });
-        }
-        else {
-            missing.push(key);
-        }
-    }
-    // Warn about missing vars
-    for (const key of missing) {
-        console.log(chalk_1.default.yellow(`⚠ ${key}: not found in ${envFileName}`));
-    }
-    if (variables.length === 0) {
-        console.log(chalk_1.default.yellow('No matching environment variables to push'));
-        return;
-    }
-    // Push to API
-    try {
-        const response = await axios_1.default.post(`${host}/api/v1/projects/${projectSlug}/variable-mappings/bulk`, { variables }, {
-            headers: {
-                'Authorization': `Bearer ${apiKey}`,
-                'Accept': 'application/json',
-                'Content-Type': 'application/json',
-            },
-        });
-        const { created, updated } = response.data;
-        console.log(chalk_1.default.green(`✓ Pushed ${variables.length} environment variables from ${envFileName}`));
-        if (created > 0 || updated > 0) {
-            console.log(chalk_1.default.gray(`  (${created} created, ${updated} updated)`));
-        }
-    }
-    catch (error) {
-        console.error(chalk_1.default.red('Failed to push environment variables:'), error.response?.data?.message || error.message);
-    }
-}
 async function deploy(projectName, sourcePath, options = {}) {
     const config = (0, init_1.getConfig)();
     if (!config?.apiKey) {
@@ -399,11 +253,6 @@ async function deploy(projectName, sourcePath, options = {}) {
                         if (yamlConfig) {
                             await pushYamlDeclarations(config.host, config.apiKey, projectSlug, yamlConfig);
                         }
-                        // Push .env values if deployEnv is enabled
-                        if (yamlConfig && isDeployEnvEnabled(yamlConfig)) {
-                            console.log(chalk_1.default.blue('\nPushing environment variables...'));
-                            await pushEnvVars(config.host, config.apiKey, projectSlug, sourceDir, environment, yamlConfig);
-                        }
                         fs_1.default.unlinkSync(zipPath);
                         process.exit(0);
                     }

package/dist/commands/env-push.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envPush = envPush;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const axios_1 = __importDefault(require("axios"));
+const chalk_1 = __importDefault(require("chalk"));
+const prompts_1 = __importDefault(require("prompts"));
+const init_1 = require("./init");
+const env_1 = require("../utils/env");
+async function envPush(projectName, sourcePath, options = {}) {
+    const config = (0, init_1.getConfig)();
+    if (!config?.apiKey) {
+        console.error(chalk_1.default.red('Not initialized. Run "solidactions init <api-key>" first.'));
+        process.exit(1);
+    }
+    const sourceDir = path_1.default.resolve(sourcePath);
+    const environment = options.env || 'dev';
+    // Read solidactions.yaml
+    const yamlPath = path_1.default.join(sourceDir, 'solidactions.yaml');
+    if (!fs_1.default.existsSync(yamlPath)) {
+        console.error(chalk_1.default.red('solidactions.yaml not found in ' + sourceDir));
+        console.log(chalk_1.default.gray('Make sure you\'re in a SolidActions project directory.'));
+        process.exit(1);
+    }
+    let yamlConfig;
+    try {
+        yamlConfig = (0, env_1.loadSolidActionsConfig)(yamlPath);
+    }
+    catch (err) {
+        console.error(chalk_1.default.red('Failed to parse solidactions.yaml:'), err.message);
+        process.exit(1);
+    }
+    // Get YAML-declared vars
+    const declaredVars = (0, env_1.getYamlDeclaredVars)(yamlConfig);
+    // Determine env file
+    const envFileName = environment === 'production' ? '.env' : `.env.${environment}`;
+    const envFilePath = path_1.default.join(sourceDir, envFileName);
+    if (!fs_1.default.existsSync(envFilePath)) {
+        console.error(chalk_1.default.red(`${envFileName} not found in ${sourceDir}`));
+        console.log(chalk_1.default.gray(`Create ${envFileName} with your environment variables, or use a different --env.`));
+        process.exit(1);
+    }
+    // Parse the .env file
+    const envValues = (0, env_1.parseEnvFile)(envFilePath);
+    if (envValues.size === 0) {
+        console.log(chalk_1.default.yellow(`${envFileName} is empty — nothing to push.`));
+        process.exit(0);
+    }
+    // Filter to YAML-declared vars only (unless --include-undeclared)
+    let keysToProcess;
+    if (options.includeUndeclared) {
+        keysToProcess = Array.from(envValues.keys());
+    }
+    else {
+        if (declaredVars.size === 0) {
+            console.log(chalk_1.default.yellow('No environment variables declared in solidactions.yaml.'));
+            console.log(chalk_1.default.gray('Use --include-undeclared to push all vars from the .env file.'));
+            process.exit(0);
+        }
+        keysToProcess = Array.from(envValues.keys()).filter(k => declaredVars.has(k));
+        // Warn about YAML-declared vars missing from .env
+        for (const key of declaredVars) {
+            if (!envValues.has(key)) {
+                console.log(chalk_1.default.yellow(`⚠ ${key}: declared in YAML but not found in ${envFileName}`));
+            }
+        }
+    }
+    if (keysToProcess.length === 0) {
+        console.log(chalk_1.default.yellow('No matching variables to push.'));
+        if (!options.includeUndeclared && envValues.size > 0) {
+            console.log(chalk_1.default.gray('Your .env has variables not declared in solidactions.yaml. Use --include-undeclared to push them.'));
+        }
+        process.exit(0);
+    }
+    // Build project slug
+    const projectSlug = environment === 'production'
+        ? projectName
+        : `${projectName}-${environment}`;
+    console.log(chalk_1.default.blue(`Pushing env vars to "${projectName}" (${environment})...`));
+    // Fetch current server state
+    let serverMappings = [];
+    try {
+        const response = await axios_1.default.get(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings`, {
+            headers: {
+                'Authorization': `Bearer ${config.apiKey}`,
+                'Accept': 'application/json',
+            },
+        });
+        serverMappings = response.data || [];
+    }
+    catch (error) {
+        if (error.response?.status === 401) {
+            console.error(chalk_1.default.red('Authentication failed. Run "solidactions init <api-key>" to re-configure.'));
+            process.exit(1);
+        }
+        else if (error.response?.status === 404) {
+            console.error(chalk_1.default.red(`Project "${projectSlug}" not found.`));
+            console.log(chalk_1.default.gray(`Deploy first with: solidactions deploy ${projectName} --env ${environment}` + (environment !== 'production' ? ' --create' : '')));
+            process.exit(1);
+        }
+        throw error;
+    }
+    // Build a lookup of server state by env_name
+    const serverState = new Map();
+    for (const mapping of serverMappings) {
+        serverState.set(mapping.env_name, mapping);
+    }
+    const entries = [];
+    for (const key of keysToProcess) {
+        const value = envValues.get(key);
+        const isSecret = /secret|key|token|password|credential/i.test(key);
+        const existing = serverState.get(key);
+        let action;
+        if (!existing || existing.status === 'not_configured' || existing.has_value === false) {
+            action = 'create';
+        }
+        else {
+            action = 'update';
+        }
+        // If --new-only, skip updates
+        if (options.newOnly && action === 'update') {
+            action = 'skip';
+        }
+        entries.push({ key, value, is_secret: isSecret, action });
+    }
+    const toCreate = entries.filter(e => e.action === 'create');
+    const toUpdate = entries.filter(e => e.action === 'update');
+    const toSkip = entries.filter(e => e.action === 'skip');
+    const toPush = entries.filter(e => e.action !== 'skip');
+    if (toPush.length === 0) {
+        console.log(chalk_1.default.yellow('Nothing to push — all variables are already configured.'));
+        if (toSkip.length > 0) {
+            console.log(chalk_1.default.gray(`${toSkip.length} variable(s) skipped (--new-only).`));
+        }
+        process.exit(0);
+    }
+    // Display diff table
+    console.log('');
+    console.log(chalk_1.default.bold('  KEY'.padEnd(36) + 'ACTION'.padEnd(12) + 'NOTES'));
+    console.log(chalk_1.default.gray('  ' + '─'.repeat(56)));
+    for (const entry of entries) {
+        const keyCol = ('  ' + entry.key).padEnd(36);
+        let actionCol;
+        let notesCol;
+        switch (entry.action) {
+            case 'create':
+                actionCol = chalk_1.default.green('create'.padEnd(12));
+                notesCol = chalk_1.default.gray('(new)');
+                break;
+            case 'update':
+                actionCol = chalk_1.default.yellow('update'.padEnd(12));
+                notesCol = chalk_1.default.gray('(has existing value)');
+                break;
+            case 'skip':
+                actionCol = chalk_1.default.gray('skip'.padEnd(12));
+                notesCol = chalk_1.default.gray('(--new-only)');
+                break;
+        }
+        console.log(keyCol + actionCol + notesCol);
+    }
+    console.log('');
+    // Confirm unless --yes
+    if (!options.yes) {
+        const summary = [];
+        if (toCreate.length > 0)
+            summary.push(`${toCreate.length} create`);
+        if (toUpdate.length > 0)
+            summary.push(`${toUpdate.length} update`);
+        if (toSkip.length > 0)
+            summary.push(`${toSkip.length} skip`);
+        const response = await (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'confirm',
+            message: `Push ${toPush.length} variable(s) to ${projectSlug}? (${summary.join(', ')})`,
+            initial: true,
+        });
+        if (!response.confirm) {
+            console.log(chalk_1.default.gray('Cancelled.'));
+            return;
+        }
+    }
+    // Push via bulk API
+    const variables = toPush.map(e => ({
+        key: e.key,
+        value: e.value,
+        is_secret: e.is_secret,
+    }));
+    try {
+        const response = await axios_1.default.post(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings/bulk`, { variables }, {
+            headers: {
+                'Authorization': `Bearer ${config.apiKey}`,
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+            },
+        });
+        const { created, updated } = response.data;
+        console.log(chalk_1.default.green(`\n✓ Pushed ${toPush.length} variable(s) to ${projectSlug}`));
+        console.log(chalk_1.default.gray(`  ${created} created, ${updated} updated` + (toSkip.length > 0 ? `, ${toSkip.length} skipped` : '')));
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('Failed to push environment variables:'), error.response?.data?.message || error.message);
+        process.exit(1);
+    }
+}

package/dist/index.js

@@ -14,11 +14,14 @@ const env_list_1 = require("./commands/env-list");
 const env_delete_1 = require("./commands/env-delete");
 const env_map_1 = require("./commands/env-map");
 const env_pull_1 = require("./commands/env-pull");
+const env_push_1 = require("./commands/env-push");
 const schedule_set_1 = require("./commands/schedule-set");
 const schedule_list_1 = require("./commands/schedule-list");
 const schedule_delete_1 = require("./commands/schedule-delete");
 const webhooks_1 = require("./commands/webhooks");
 const dev_1 = require("./commands/dev");
+const ai_init_1 = require("./commands/ai-init");
+const ai_examples_1 = require("./commands/ai-examples");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
 const program = new commander_1.Command();
@@ -173,6 +176,18 @@ program
     .action((project, options) => {
     (0, env_pull_1.envPull)(project, options);
 });
+program
+    .command('env:push')
+    .description('Push environment variables from .env file to a project')
+    .argument('<project>', 'Project name')
+    .argument('[path]', 'Source directory with solidactions.yaml and .env file', '.')
+    .option('-e, --env <environment>', 'Target environment (production/staging/dev)', 'dev')
+    .option('--new-only', 'Only push new or empty variables (skip existing)')
+    .option('--include-undeclared', 'Also push vars not declared in solidactions.yaml')
+    .option('-y, --yes', 'Skip confirmation prompt')
+    .action((project, path, options) => {
+    (0, env_push_1.envPush)(project, path, options);
+});
 // =============================================================================
 // Scheduling
 // =============================================================================
@@ -214,4 +229,20 @@ program
     .action((project, options) => {
     (0, webhooks_1.webhookList)(project, options);
 });
+// =============================================================================
+// AI Helper
+// =============================================================================
+program
+    .command('ai:init')
+    .description('Install AI helper documentation (CLAUDE.md or AGENTS.md) for AI-assisted workflow development')
+    .option('--claude', 'Use CLAUDE.md (for Claude Code)')
+    .option('--agents', 'Use AGENTS.md (for Cursor, Windsurf, etc.)')
+    .action((options) => { (0, ai_init_1.aiInit)(options); });
+program
+    .command('ai:examples')
+    .description('Install example workflows for AI reference')
+    .argument('[names...]', 'Example names to install (omit for interactive selector)')
+    .option('--all', 'Install all available examples')
+    .option('--overwrite', 'Overwrite existing examples without warning')
+    .action((names, options) => { (0, ai_examples_1.aiExamples)(names, options); });
 program.parse();

package/dist/utils/env.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvFile = parseEnvFile;
+exports.parseYamlEnvVars = parseYamlEnvVars;
+exports.getYamlDeclaredVars = getYamlDeclaredVars;
+exports.loadSolidActionsConfig = loadSolidActionsConfig;
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+/**
+ * Parse a .env file into a key-value map.
+ */
+function parseEnvFile(filePath) {
+    const envMap = new Map();
+    if (!fs_1.default.existsSync(filePath)) {
+        return envMap;
+    }
+    const content = fs_1.default.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip empty lines and comments
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const equalsIndex = trimmed.indexOf('=');
+        if (equalsIndex === -1) {
+            continue;
+        }
+        const key = trimmed.substring(0, equalsIndex).trim();
+        let value = trimmed.substring(equalsIndex + 1).trim();
+        // Remove surrounding quotes if present
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        envMap.set(key, value);
+    }
+    return envMap;
+}
+/**
+ * Parse YAML env declarations into structured format.
+ * Handles the new simplified format:
+ *   - VAR_NAME           -> { key: "VAR_NAME", mappedTo: null }
+ *   - VAR_NAME: GLOBAL   -> { key: "VAR_NAME", mappedTo: "GLOBAL" }
+ */
+function parseYamlEnvVars(config) {
+    const parsedVars = [];
+    if (!config.env || !Array.isArray(config.env)) {
+        return parsedVars;
+    }
+    for (const item of config.env) {
+        if (typeof item === 'string') {
+            // Simple string: - VAR_NAME (declared only, needs configuration)
+            parsedVars.push({ key: item, mappedTo: null, oauthName: null });
+        }
+        else if (typeof item === 'object' && item !== null) {
+            // Object: - VAR_NAME: GLOBAL_NAME or - VAR_NAME: { oauth: connection-name }
+            const keys = Object.keys(item);
+            if (keys.length === 1) {
+                const key = keys[0];
+                const value = item[key];
+                if (typeof value === 'object' && value !== null && 'oauth' in value) {
+                    if (typeof value.oauth !== 'string' || !value.oauth) {
+                        throw new Error(`Invalid env config for ${key}: 'oauth' must be a non-empty string`);
+                    }
+                    parsedVars.push({ key, mappedTo: null, oauthName: value.oauth });
+                }
+                else {
+                    parsedVars.push({ key, mappedTo: value || null, oauthName: null });
+                }
+            }
+        }
+    }
+    return parsedVars;
+}
+/**
+ * Extract declared variable keys from solidactions.yaml env config.
+ * Returns a set of env var keys that are declared in YAML.
+ */
+function getYamlDeclaredVars(config) {
+    const parsedVars = parseYamlEnvVars(config);
+    return new Set(parsedVars.map(v => v.key));
+}
+/**
+ * Load and parse a solidactions.yaml config file.
+ */
+function loadSolidActionsConfig(yamlPath) {
+    const content = fs_1.default.readFileSync(yamlPath, 'utf8');
+    return js_yaml_1.default.load(content);
+}

package/dist/utils/github.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchRawFile = fetchRawFile;
+exports.listRepoContents = listRepoContents;
+const axios_1 = __importDefault(require("axios"));
+async function fetchRawFile(owner, repo, path, branch = 'main') {
+    try {
+        const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+        const response = await axios_1.default.get(url, { responseType: 'text' });
+        return response.data;
+    }
+    catch (error) {
+        if (error.response?.status === 404) {
+            throw new Error(`File not found: ${owner}/${repo}/${path} (branch: ${branch})`);
+        }
+        throw new Error(`Failed to fetch ${owner}/${repo}/${path}: ${error.message}`);
+    }
+}
+async function listRepoContents(owner, repo, path = '', branch = 'main') {
+    try {
+        const url = `https://api.github.com/repos/${owner}/${repo}/contents/${path}?ref=${branch}`;
+        const response = await axios_1.default.get(url);
+        return response.data.map((item) => ({
+            name: item.name,
+            type: item.type,
+            download_url: item.download_url,
+        }));
+    }
+    catch (error) {
+        if (error.response?.status === 403) {
+            throw new Error('GitHub API rate limit reached (60 requests/hour for unauthenticated access). Please wait a few minutes and try again.');
+        }
+        if (error.response?.status === 404) {
+            throw new Error(`Repository or path not found: ${owner}/${repo}/${path}`);
+        }
+        throw new Error(`Failed to list ${owner}/${repo}/${path}: ${error.message}`);
+    }
+}

package/dist/utils/markers.js

@@ -0,0 +1,45 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertMarkerSection = upsertMarkerSection;
+exports.hasMarkerSection = hasMarkerSection;
+exports.findAiHelperFile = findAiHelperFile;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+function upsertMarkerSection(filePath, markerName, content) {
+    fs_extra_1.default.ensureDirSync(path_1.default.dirname(filePath));
+    let existing = '';
+    if (fs_1.default.existsSync(filePath)) {
+        existing = fs_1.default.readFileSync(filePath, 'utf8');
+    }
+    const openTag = `<!-- ${markerName} -->`;
+    const closeTag = `<!-- /${markerName} -->`;
+    const block = `${openTag}\n${content}\n${closeTag}`;
+    const openIdx = existing.indexOf(openTag);
+    const closeIdx = existing.indexOf(closeTag);
+    if (openIdx !== -1 && closeIdx !== -1) {
+        const before = existing.substring(0, openIdx);
+        const after = existing.substring(closeIdx + closeTag.length);
+        fs_1.default.writeFileSync(filePath, before + block + after, 'utf8');
+    }
+    else {
+        const result = existing.length > 0 ? existing + '\n\n' + block + '\n' : block + '\n';
+        fs_1.default.writeFileSync(filePath, result, 'utf8');
+    }
+}
+function hasMarkerSection(filePath, markerName) {
+    if (!fs_1.default.existsSync(filePath))
+        return false;
+    const content = fs_1.default.readFileSync(filePath, 'utf8');
+    return content.includes(`<!-- ${markerName} -->`) && content.includes(`<!-- /${markerName} -->`);
+}
+function findAiHelperFile() {
+    if (hasMarkerSection('CLAUDE.md', 'SolidActions'))
+        return 'CLAUDE.md';
+    if (hasMarkerSection('AGENTS.md', 'SolidActions'))
+        return 'AGENTS.md';
+    return null;
+}

package/package.json

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