@solidactions/cli 0.5.0 → 0.6.1

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/index.js

@@ -20,6 +20,8 @@ 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();
@@ -227,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/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.5.0",
+    "version": "0.6.1",
     "description": "SolidActions CLI - Deploy and manage workflow automation",
     "main": "dist/index.js",
     "bin": {