@solidactions/cli 1.3.0 → 1.6.0

package/README.md

@@ -12,7 +12,7 @@ npm install -g @solidactions/cli
 
 ```bash
 solidactions init <api-key>                          # Initialize (prompts for workspace)
-solidactions init <api-key> --workspace <name>       # Initialize with workspace
+solidactions ai init                                  # Install AI skills and SDK reference (required for AI-assisted dev)
 solidactions project deploy <project> <path>         # Deploy a project
 solidactions run start <project> <workflow>           # Trigger a workflow
 solidactions run view <run-id>                        # Inspect a run
@@ -127,9 +127,21 @@ Use `solidactions <command> --help` for full flag details on any command.
 
 | Command | Key Flags | Description |
 |---------|-----------|-------------|
-| `ai init` | `--claude`, `--agents` | Install AI helper docs |
+| `ai init` | `--claude`, `--agents` | Install AI skills and SDK reference |
 | `ai examples [names...]` | `--all`, `--overwrite` | Install example workflows |
 
+`ai init` installs three auto-activating SolidActions skills and a
+full SDK reference into your project:
+
+- Skills go to `.claude/skills/` (for `--claude` / Claude Code) or
+  `.agents/skills/` (for `--agents` / Codex, Cursor, Gemini, Windsurf).
+  Codex auto-discovers the `.agents/skills/` path — see
+  https://developers.openai.com/codex/skills.
+- The SDK reference is saved to `.solidactions/sdk-reference.md`.
+- A slim pointer section is injected into `CLAUDE.md` or `AGENTS.md`
+  listing the skills and inlining the highest-cost hard rules
+  (determinism, step discipline, messaging) as a safety net.
+
 ## Development
 
 ```bash

package/dist/commands/ai-init.js

@@ -8,11 +8,13 @@ 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 path_1 = __importDefault(require("path"));
 const github_1 = require("../utils/github");
 const markers_1 = require("../utils/markers");
+const skills_1 = require("../utils/skills");
 async function aiInit(options = {}) {
     try {
-        // Determine target file
+        // Determine target file.
         let targetFile;
         if (options.claude && options.agents) {
             console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
@@ -30,8 +32,8 @@ async function aiInit(options = {}) {
                 name: 'file',
                 message: 'Which AI helper file?',
                 choices: [
-                    { title: 'CLAUDE.md', value: 'CLAUDE.md' },
-                    { title: 'AGENTS.md', value: 'AGENTS.md' },
+                    { title: 'CLAUDE.md (Claude Code)', value: 'CLAUDE.md' },
+                    { title: 'AGENTS.md (Codex, Cursor, Gemini, etc.)', value: 'AGENTS.md' },
                 ],
             });
             if (!response.file) {
@@ -41,22 +43,26 @@ async function aiInit(options = {}) {
             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
+        // Fetch slim helper content for the chosen target.
+        const aiContent = await (0, skills_1.fetchAiHelperContent)(targetFile);
+        // Fetch SDK reference (always).
         const sdkContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-ts-sdk', 'docs/sdk-reference.md');
-        // Save SDK reference to .solidactions/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
+        // Always install skills — no prompt. The user chose `ai init <target>`,
+        // so they want AI tooling set up.
+        const targetDir = (0, skills_1.skillTargetDir)(targetFile);
+        console.log(chalk_1.default.blue(`Installing SolidActions skills to ${path_1.default.relative(process.cwd(), targetDir)}/ ...`));
+        const { written } = await (0, skills_1.installSkills)(targetDir);
+        for (const f of written) {
+            console.log(chalk_1.default.green(`✓ ${path_1.default.relative(process.cwd(), f)}`));
+        }
+        // Upsert the AI helper marker 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}`));
+        console.log(chalk_1.default.gray('  Existing files may still contain a separate "SolidActions SDK Reference" marker block from older CLI versions. That content is now redundant and can be deleted manually.'));
     }
     catch (error) {
         if (error.message?.includes('rate limit')) {

package/dist/commands/deploy.js

@@ -114,11 +114,51 @@ async function pushYamlDeclarations(config, projectSlug, yamlConfig) {
 async function deploy(projectName, sourcePath, options = {}) {
     const config = await (0, api_1.requireConfigWithWorkspace)();
     const sourceDir = sourcePath ? path_1.default.resolve(sourcePath) : process.cwd();
-    const environment = options.env || 'dev';
+    // Capture whether -e was explicitly passed by the caller. Commander leaves
+    // options.env as undefined when no default is set and the flag is omitted.
+    const explicitEnv = options.env;
     if (!fs_1.default.existsSync(sourceDir)) {
         console.error(chalk_1.default.red(`Source directory not found: ${sourceDir}`));
         process.exit(1);
     }
+    // -------------------------------------------------------------------------
+    // Production-existence check — must happen BEFORE we apply any env default
+    // so that first-time deploys without -e get a helpful error instead of
+    // silently creating a dev-only project with no production root.
+    // -------------------------------------------------------------------------
+    let productionExists = null; // null = unknown (error path)
+    let productionSlug = null;
+    try {
+        const prodResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${projectName}`, {
+            headers: (0, api_1.getApiHeaders)(config),
+        });
+        productionExists = true;
+        productionSlug = prodResponse.data.slug || prodResponse.data.name;
+    }
+    catch (error) {
+        if (error.response?.status === 404) {
+            productionExists = false;
+        }
+        else {
+            // 5xx, network error, auth failure, etc. — fail conservatively rather
+            // than treating the project as non-existent and potentially creating it.
+            console.error(chalk_1.default.red('Failed to check project existence:'), error.response?.data?.message || error.message);
+            process.exit(1);
+        }
+    }
+    // Decision: if production does not exist and no -e flag was given, the user
+    // must pick an environment explicitly to avoid creating a broken dev-only project.
+    if (productionExists === false && explicitEnv === undefined) {
+        console.error(chalk_1.default.red(`\nThis is the first deploy of "${projectName}" — please pick an environment explicitly:\n`));
+        console.error(`  solidactions project deploy ${projectName} <path> -e production    # most projects start here`);
+        console.error(`  solidactions project deploy ${projectName} <path> -e dev            # dev-only (uncommon; no production root will exist)`);
+        console.error(`  solidactions project deploy ${projectName} <path> -e staging        # staging-only (uncommon)`);
+        console.error(chalk_1.default.gray('\nTip: most projects should start with `-e production`. A project needs a production root before dev/staging children can attach to it.'));
+        process.exit(1);
+    }
+    // Apply default: if production already exists and the user didn't pass -e,
+    // use 'dev' — this preserves existing behavior for mature projects.
+    const environment = explicitEnv ?? 'dev';
     const envLabel = environment !== 'production' ? ` (${environment})` : '';
     console.log(chalk_1.default.blue(`Deploying to project "${projectName}"${envLabel}...`));
     console.log(chalk_1.default.gray(`Source: ${sourceDir}`));
@@ -149,24 +189,36 @@ async function deploy(projectName, sourcePath, options = {}) {
         process.exit(1);
     }
     console.log(chalk_1.default.green('✓ Project structure validated'));
-    // Check if project exists, create if not
+    // Check if the target environment's project record exists; create if needed.
+    // For production deploys where we already confirmed existence above, reuse
+    // the cached slug to avoid a duplicate GET.
     let projectSlug = projectName;
     try {
-        // For non-production environments, append the environment to the slug for lookup
-        const lookupSlug = environment === 'production'
-            ? projectName
-            : `${projectName}-${environment}`;
-        const checkResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${lookupSlug}`, {
-            headers: (0, api_1.getApiHeaders)(config),
-        });
-        projectSlug = checkResponse.data.slug || checkResponse.data.name;
+        if (environment === 'production' && productionExists === true && productionSlug !== null) {
+            // Already confirmed — skip the re-lookup.
+            projectSlug = productionSlug;
+        }
+        else {
+            // For non-production environments, append the environment to the slug for lookup
+            const lookupSlug = environment === 'production'
+                ? projectName
+                : `${projectName}-${environment}`;
+            const checkResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${lookupSlug}`, {
+                headers: (0, api_1.getApiHeaders)(config),
+            });
+            projectSlug = checkResponse.data.slug || checkResponse.data.name;
+        }
     }
     catch (error) {
         if (error.response?.status === 404) {
-            // For non-production environments, check if we should create
+            // For non-production environments, require --create or give a clear hint
             if (environment !== 'production' && !options.create) {
-                console.log(chalk_1.default.yellow(`Project "${projectName}" doesn't have a ${environment} environment.`));
-                console.log(chalk_1.default.gray('Use --create to create it, or deploy to production first.'));
+                console.error(chalk_1.default.red(`\nProject "${projectName}" doesn't have a ${environment} environment.\n`));
+                console.error(`  If production is the intended target:`);
+                console.error(`    solidactions project deploy ${projectName} <path> -e production`);
+                console.error('');
+                console.error(`  If you really want a new ${environment} environment:`);
+                console.error(`    solidactions project deploy ${projectName} <path> -e ${environment} --create`);
                 process.exit(1);
             }
             console.log(chalk_1.default.yellow(`Project "${projectName}"${envLabel} not found. Creating...`));

package/dist/commands/init.js

@@ -152,6 +152,9 @@ async function init(apiKey, options) {
         console.log(chalk_1.default.yellow('Could not set workspace. Run `solidactions workspace set` later.'));
     }
     console.log('');
+    console.log(chalk_1.default.blue('Next step — install AI helper docs and skills:'));
+    console.log(chalk_1.default.gray('  solidactions ai init                  Picks CLAUDE.md or AGENTS.md interactively'));
+    console.log('');
     console.log(chalk_1.default.blue('Quick start:'));
     console.log(chalk_1.default.gray('  solidactions project deploy <name>    Deploy current directory'));
     console.log(chalk_1.default.gray('  solidactions run start <proj> <wf>    Run a workflow'));

package/dist/index.js

@@ -104,7 +104,7 @@ project
     .description('Deploy a project to SolidActions')
     .argument('<project-name>', 'Project name (will be created if it doesn\'t exist)')
     .argument('[path]', 'Source directory to deploy (defaults to current directory)')
-    .option('-e, --env <environment>', 'Target environment (production/staging/dev)', 'dev')
+    .option('-e, --env <environment>', 'Target environment (production/staging/dev). Required on first deploy of a new project.')
     .option('--create', 'Create environment project if it doesn\'t exist')
     .option('--config-only', 'Sync YAML env declarations without building/deploying')
     .action((projectName, path, options) => {
@@ -311,9 +311,9 @@ workspace
 const ai = program.command('ai').description('AI helper tools');
 ai
     .command('init')
-    .description('Install AI helper documentation (CLAUDE.md or AGENTS.md) for AI-assisted workflow development')
+    .description('Install SolidActions AI skills and SDK reference for AI-assisted development')
     .option('--claude', 'Use CLAUDE.md (for Claude Code)')
-    .option('--agents', 'Use AGENTS.md (for Cursor, Windsurf, etc.)')
+    .option('--agents', 'Use AGENTS.md (for Codex, Cursor, Gemini, Windsurf, etc.)')
     .action((options) => { (0, ai_init_1.aiInit)(options); });
 ai
     .command('examples')

package/dist/utils/skills.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillTargetDir = skillTargetDir;
+exports.installSkills = installSkills;
+exports.fetchAiHelperContent = fetchAiHelperContent;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const github_1 = require("./github");
+const SKILL_NAMES = [
+    'solidactions-getting-started',
+    'solidactions-workflow-coding',
+    'solidactions-deploy-and-config',
+];
+const EXAMPLES_OWNER = 'SolidActions';
+const EXAMPLES_REPO = 'solidactions-examples';
+const SKILLS_PATH_PREFIX = 'skills';
+/**
+ * Resolve the skills directory for an AI helper target.
+ *
+ * - `CLAUDE.md` → `<cwd>/.claude/skills/` (Claude Code convention)
+ * - `AGENTS.md` → `<cwd>/.agents/skills/` (Codex auto-discovers this path;
+ *   Cursor/Gemini read via AGENTS.md pointers)
+ *
+ * The directory does not need to exist — the caller creates it.
+ */
+function skillTargetDir(targetFile, cwd = process.cwd()) {
+    if (targetFile === 'CLAUDE.md') {
+        return path_1.default.join(cwd, '.claude', 'skills');
+    }
+    return path_1.default.join(cwd, '.agents', 'skills');
+}
+/**
+ * Fetch all SolidActions skill files from the examples repo and write
+ * them into the target directory. Overwrites existing files (skills
+ * are versioned upstream).
+ */
+async function installSkills(targetDir) {
+    const written = [];
+    fs_extra_1.default.ensureDirSync(targetDir);
+    for (const skillName of SKILL_NAMES) {
+        const remotePath = `${SKILLS_PATH_PREFIX}/${skillName}.md`;
+        const content = await (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, remotePath);
+        const filePath = path_1.default.join(targetDir, `${skillName}.md`);
+        fs_1.default.writeFileSync(filePath, content, 'utf8');
+        written.push(filePath);
+    }
+    return { written };
+}
+/**
+ * Fetch the slim AI-helper content for the target file from the examples
+ * repo. Single source per target — no legacy fallback.
+ */
+async function fetchAiHelperContent(targetFile) {
+    return (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, targetFile);
+}

package/package.json

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