@aksp/opencrew 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.2.2] — 2026-08-02
+
+### Fixed
+- **`parseArgs` truncates values containing `=`**: flags like `--description=foo=bar`
+  no longer lose everything after the second `=`.
+- **`version` npm script uses `require()` in ESM project**: extracted to a dedicated
+  `scripts/stamp-version.js` that uses proper ESM imports.
+- **`skills.engine.md` numbering was out of order** in Operation 2 (Install a Skill):
+  steps 3/4 repeated instead of continuing 5–9. Cross-references updated accordingly.
+- **`init` now aborts when a workspace already exists** instead of proceeding with
+  `overwrite: false` (which silently did nothing). It prints instructions to use
+  `update` or reinstall from scratch.
+- **`deleteDir` semantics**: now returns `false` when the path does not exist (was `true`).
+- **`.env.example` placeholders** (`[REDACTED:API key param]`) removed — these were
+  security-redaction artifacts from the tooling, not real file content. No code change.
+
+### Added
+- **Short flags**: `-y` (yes), `-v` (version), `-h` (help) now work alongside their
+  `--long-form` equivalents.
+- **`OPENCREW_CATALOG_URL` env var**: forks can override the skill catalog base URL
+  without editing `catalog.json`. Documented in `CONTRIBUTING.md` → Forking.
+- **`update` now warns** that catalog skills are fully overwritten before refreshing them.
+- **`readJson` error messages now include the file path** (e.g. `Failed to read
+  /path/to/package.json: file not found`).
+- **`pickIdes` validates preselected IDs**: unknown IDs from `--ide` are filtered with
+  a warning instead of being passed through silently.
+- **`c.gray` removed** (unused). **`confirm()` removed** (dead code, never imported).
+- **ESLint** (`eslint.config.js` + `npm run lint` + CI step) with `@eslint/js` flat config.
+- **55 tests** (up from 30): new coverage for `paths.js`, `ui.js`, `fsx.js` error
+  scenarios, `normalizeIdes` string input, CLI smoke tests.
+
+### Changed
+- **CI `npm audit` raised from `moderate` to `high`** to avoid spurious build failures
+  from dev-dependency vulnerabilities without attack vectors.
+- **Playwright config**: `channel: "chrome"` removed — uses bundled Chromium for better
+  portability. `.mcp.json` now includes a `_comment` field explaining how to upgrade the
+  pinned `@playwright/mcp` version.
+- **Node version check** in `cli.js` now uses a proper semver comparison that handles
+  `||` ranges (e.g. `>=18.0.0 || >=20.0.0`).
+
+### Docs
+- **`discovery.prompt.md`**: `crew_code` uniqueness is now self-service (`ls crews/`)
+  instead of depending on the orchestrator to pass a list.
+- **`runner.pipeline.md`**: language contract table documents all fixed PT-BR headers
+  and the policy for adding new ones.
+- **`CONTRIBUTING.md`**: new "Forking" section with catalog URL, package name, and
+  publish instructions.
+
 ## [1.2.1] — 2026-08-02
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "publishConfig": {
     "access": "public"
   },
@@ -19,8 +19,9 @@
   ],
   "scripts": {
     "start": "node bin/opencrew.js",
-    "test": "node --test tests/cli.test.js tests/docs.test.js tests/fsx.test.js tests/ides.test.js tests/init.test.js tests/update.test.js",
-    "version": "node -e \"require('fs').writeFileSync('templates/_opencrew/.opencrew-version', require('./package.json').version + '\\n')\" && git add templates/_opencrew/.opencrew-version"
+    "test": "node --test tests/cli.test.js tests/docs.test.js tests/fsx.test.js tests/ides.test.js tests/init.test.js tests/paths.test.js tests/ui.test.js tests/update.test.js",
+    "lint": "eslint src/ tests/ scripts/",
+    "version": "node scripts/stamp-version.js && git add templates/_opencrew/.opencrew-version"
   },
   "keywords": [
     "ai-agents",
@@ -53,5 +54,10 @@
   "dependencies": {
     "@inquirer/checkbox": "^5.1.0",
     "@inquirer/confirm": "^5.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^17.9.0"
   }
 }

package/src/cli.js

@@ -5,16 +5,52 @@ import { init } from './commands/init.js';
 import { update } from './commands/update.js';
 import { c, log, err, warn, info } from './lib/ui.js';
 
+// Extract the minimum required Node version from an engines.node range string.
+// Handles: ">=20.0.0", "^20.5", ">=18.0.0 || >=20.0.0", plain "20.0.0".
+function minNodeVersion(range) {
+  // Split on || and take the lowest version (user is expected to meet at least one).
+  const parts = range.split(/\s*\|\|\s*/);
+  let lowest = null;
+  for (const part of parts) {
+    const v = part.replace(/[^0-9.]/g, '');
+    if (!v) continue;
+    if (!lowest || lt(v, lowest)) lowest = v;
+  }
+  return lowest;
+}
+
+// Simple semver comparison (no prerelease tags). Returns true if a < b.
+function lt(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na !== nb) return na < nb;
+  }
+  return false; // equal
+}
+
 function parseArgs(argv) {
   const opts = { _: [] };
   for (const a of argv) {
     if (a.startsWith('--')) {
-      const [k, v] = a.slice(2).split('=');
-      opts[k] = v === undefined ? true : v;
+      const eq = a.indexOf('=');
+      const k = eq > -1 ? a.slice(2, eq) : a.slice(2);
+      const v = eq > -1 ? a.slice(eq + 1) : true;
+      opts[k] = v;
+    } else if (a.startsWith('-') && a.length === 2) {
+      // Short flags: -y → yes, -v → version, -h → help
+      const short = a[1];
+      opts[short] = true;
     } else {
       opts._.push(a);
     }
   }
+  // Normalize short flags to their long-form equivalents.
+  if (opts.y) opts.yes = true;
+  if (opts.v) opts.version = true;
+  if (opts.h) opts.help = true;
   return opts;
 }
 
@@ -28,13 +64,14 @@ ${c.bold('Usage')}
 ${c.bold('Commands')}
   init            Scaffold an opencrew workspace in the current folder
   update          Refresh the framework (keeps your crews, memory and .env)
+  upgrade         Alias for update
   help            Show this help
   version         Print the version
 
 ${c.bold('Options for init')}
   --ide=a,b       Preselect IDEs (skip the prompt). Valid: ${allIdeIds().join(', ')}
   --all           Configure every supported IDE
-  --yes           Non-interactive; accept defaults
+  --yes, -y       Non-interactive; accept defaults
 
 ${c.bold('Options for update')}
   --check         Dry-run: report whether an update is available without making changes
@@ -43,6 +80,7 @@ ${c.bold('Examples')}
   npx @aksp/opencrew init
   npx @aksp/opencrew init --ide=claude-code,codex
   npx @aksp/opencrew init --all
+  npx @aksp/opencrew init -y
   npx @aksp/opencrew update
   npx @aksp/opencrew update --check
 `);
@@ -66,16 +104,13 @@ export async function run(argv) {
 
   // Validate Node version against engines.node requirement.
   if (engines.node) {
-    const min = engines.node.replace(/[^0-9.]/g, '');
-    if (min) {
-      const major = Number(min.split('.')[0]);
-      const current = Number(process.versions.node.split('.')[0]);
-      if (current < major) {
-        warn(`opencrew requires Node.js ${engines.node}. You have v${process.versions.node}.`);
-        info(`Upgrade Node or use a compatible version.`);
-        process.exitCode = 1;
-        return;
-      }
+    const required = minNodeVersion(engines.node);
+    const current = process.versions.node;
+    if (required && lt(current, required)) {
+      warn(`opencrew requires Node.js ${engines.node}. You have v${current}.`);
+      info(`Upgrade Node or use a compatible version.`);
+      process.exitCode = 1;
+      return;
     }
   }
 

package/src/commands/init.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { templatesDir, packageJsonPath } from '../lib/paths.js';
 import { copyDir, exists, writeFileSafe, readJson } from '../lib/fsx.js';
-import { IDES, ideById, allIdeIds } from '../lib/ides.js';
+import { ideById, allIdeIds } from '../lib/ides.js';
 import { pickIdes } from '../lib/prompts.js';
 import { c, log, info, ok, warn, step } from '../lib/ui.js';
 
@@ -17,8 +17,9 @@ export async function init(opts = {}) {
   const alreadyInstalled = await exists(path.join(target, '_opencrew', 'core'));
   if (alreadyInstalled) {
     warn('An opencrew workspace already exists here.');
-    warn(`Framework files are refreshed but your crews, memory and .env are kept intact.`);
-    warn(`To update only the framework, use: ${c.cyan('npx @aksp/opencrew update')}\n`);
+    info(`To update only the framework, use: ${c.cyan('npx @aksp/opencrew update')}`);
+    info(`To reinstall from scratch, delete _opencrew/ first, then run init again.`);
+    return;
   }
 
   // 1. Copy the framework payload (never clobber user work).

package/src/commands/update.js

@@ -59,6 +59,7 @@ export async function update(opts = {}) {
   // the catalog — are never touched, since copyDir only visits paths that exist
   // in the source (templates/skills/).
   step('Refreshing catalog skills');
+  warn('Catalog skills are fully overwritten — your edits to any built-in skill files will be lost.');
   let s = 0;
   await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), {
     overwrite: true,

package/src/lib/fsx.js

@@ -57,6 +57,7 @@ export async function writeFileSafe(p, content, { overwrite = true } = {}) {
  * @returns {Promise<boolean>} true if something was deleted, false if it didn't exist.
  */
 export async function deleteDir(p) {
+  if (!(await exists(p))) return false;
   try {
     await fs.rm(p, { recursive: true, force: true });
     return true;
@@ -66,5 +67,10 @@ export async function deleteDir(p) {
 }
 
 export async function readJson(p) {
-  return JSON.parse(await fs.readFile(p, 'utf8'));
+  try {
+    return JSON.parse(await fs.readFile(p, 'utf8'));
+  } catch (e) {
+    const reason = e.code === 'ENOENT' ? 'file not found' : e.message;
+    throw new Error(`Failed to read ${p}: ${reason}`);
+  }
 }

package/src/lib/prompts.js

@@ -4,9 +4,22 @@ import { IDES, allIdeIds } from './ides.js';
 import { warn } from './ui.js';
 
 export async function pickIdes({ preselected } = {}) {
+  const validIds = new Set(allIdeIds());
   const isTTY = process.stdin.isTTY && process.stdout.isTTY;
+
+  // Filter and validate preselected IDs.
+  let chosen = preselected?.length ? preselected : null;
+  if (chosen) {
+    const invalid = chosen.filter((id) => !validIds.has(id));
+    if (invalid.length) {
+      warn(`Unknown IDE(s) ignored: ${invalid.join(', ')}. Valid: ${allIdeIds().join(', ')}`);
+      chosen = chosen.filter((id) => validIds.has(id));
+    }
+    if (!chosen.length) chosen = null; // fall through to defaults
+  }
+
   if (!isTTY) {
-    const chosen = preselected?.length ? preselected : allIdeIds();
+    if (!chosen) chosen = allIdeIds();
     warn(`Non-interactive terminal — configuring IDEs: ${chosen.join(', ')}`);
     return chosen;
   }
@@ -18,7 +31,7 @@ export async function pickIdes({ preselected } = {}) {
       ...IDES.map((i) => ({
         name: i.label,
         value: i.id,
-        checked: preselected ? preselected.includes(i.id) : i.id === 'claude-code',
+        checked: chosen ? chosen.includes(i.id) : i.id === 'claude-code',
       })),
       new Separator(),
     ],
@@ -26,10 +39,3 @@ export async function pickIdes({ preselected } = {}) {
   });
   return answer;
 }
-
-export async function confirm(message, def = true) {
-  const isTTY = process.stdin.isTTY && process.stdout.isTTY;
-  if (!isTTY) return def;
-  const { default: confirmPrompt } = await import('@inquirer/confirm');
-  return confirmPrompt({ message, default: def });
-}

package/src/lib/ui.js

@@ -9,7 +9,6 @@ export const c = {
   yellow: wrap('33'),
   cyan: wrap('36'),
   red: wrap('31'),
-  gray: wrap('90'),
 };
 
 export const log = (...a) => console.log(...a);

package/templates/.mcp.json

@@ -1,4 +1,5 @@
 {
+  "_comment": "The Playwright MCP version is pinned for stability. To upgrade: npx @playwright/mcp@latest --version, then update the version below and run 'npx @aksp/opencrew update' to refresh.",
   "mcpServers": {
     "playwright": {
       "command": "npx",

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.2.1
+1.2.2

package/templates/_opencrew/config/playwright.config.json

@@ -4,8 +4,7 @@
     "isolated": false,
     "userDataDir": "_opencrew/_browser_profile",
     "launchOptions": {
-      "headless": true,
-      "channel": "chrome"
+      "headless": true
     }
   }
 }

package/templates/_opencrew/core/prompts/discovery.prompt.md

@@ -251,7 +251,7 @@ target_formats:  # content crews only; empty list for others
 
 The `crew_code` must be a short, URL-safe slug derived from the crew's purpose (e.g., `content-calendar`, `competitor-tracker`, `lead-notify`).
 
-**CRITICAL — Name uniqueness:** The `crew_code` MUST NEVER match any existing folder name in `crews/`. You will receive a list of existing crew names. If the slug you derive already exists, append a numeric suffix (`-2`, `-3`, etc.) to guarantee uniqueness. Never reuse an existing crew folder name — doing so would overwrite another crew's files.
+**CRITICAL — Name uniqueness:** The `crew_code` MUST NEVER match any existing folder name in `crews/`. Before finalizing, run `ls crews/ 2>/dev/null` (Bash) to list existing crew directories. If the slug you derive matches an existing folder, append a numeric suffix (`-2`, `-3`, etc.) until it is unique. Never reuse an existing crew folder name — doing so would overwrite another crew's files.
 
 ---
 

package/templates/_opencrew/core/runner.pipeline.md

@@ -28,7 +28,23 @@ Before starting execution:
     when `false`, skip ALL of them; never create, update, or delete
     `crews/{name}/state.json`.
 
-> **Note on language**: the section headers below (`## Estilo de Escrita`, `## Design Visual`, etc.) and the `runs.md` table columns (`Data | Run ID | Tema | ...`) are fixed PT-BR structural labels, not translated per Output Language — opencrew's primary supported audience is PT-BR (see AGENTS.md → Language Handling). Only the *content* written under these headers follows the user's preferred language.
+> **Note on language**: The structural labels listed below are **fixed PT-BR** and must
+> never be translated — opencrew's primary supported audience is PT-BR (see AGENTS.md →
+> Language Handling). Only the *content* written under these headers follows the user's
+> preferred language.
+>
+> | Fixed PT-BR header | Location | Purpose |
+> |---|---|---|
+> | `## Estilo de Escrita` | `memories.md` | Writing style rules accumulated per crew |
+> | `## Design Visual` | `memories.md` | Visual design preferences per crew |
+> | `## Estrutura de Conteúdo` | `memories.md` | Content structure rules per crew |
+> | `## Proibições Explícitas` | `memories.md` | User bans and hard blocks per crew |
+> | `## Técnico (específico do crew)` | `memories.md` | Technical crew-specific settings |
+> | `Data \| Run ID \| Tema \| Output \| Resultado` | `runs.md` | Run history table columns |
+>
+> When adding new structural sections to `memories.md` or `runs.md`, keep headers in PT-BR
+> unless the user base expands beyond PT-BR — at that point, discuss a migration strategy
+> (e.g. i18n key mapping) rather than mixing languages in a single file.
 
 1b. **Memory format migration** — After loading `memories.md`, check whether it uses the new format by scanning for the `## Estilo de Escrita` section header:
    ```bash

package/templates/_opencrew/core/skills.engine.md

@@ -20,10 +20,11 @@ You are the Skills Engine. Your job is to manage skill integrations for opencrew
 ### Catalog URL Resolution
 
 When fetching skill files from the catalog, resolve the base URL in this order:
-1. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
-2. If not available, default to:
+1. Check the `OPENCREW_CATALOG_URL` environment variable — if set, use it directly as the base URL. This allows forks to point to their own catalog without editing catalog.json.
+2. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
+3. If not available, default to:
    `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills`
-3. Append `/<name>/SKILL.md` (or other file paths) to the base URL
+4. Append `/<name>/SKILL.md` (or other file paths) to the base URL
 
 ## How Skills Are Detected
 
@@ -122,21 +123,21 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
    - If fetch fails (404 or network error) → **ERROR**: "Skill '<name>' not found in the skills catalog."
    - Do NOT proceed if the SKILL.md cannot be fetched.
 
-3. **Create the skill directory**:
+5. **Create the skill directory**:
    ```
    skills/<name>/
    ```
 
-4. **Write SKILL.md** to `skills/<name>/SKILL.md`
+6. **Write SKILL.md** to `skills/<name>/SKILL.md`
 
-5. **Fetch additional files** (if the skill requires them):
+7. **Fetch additional files** (if the skill requires them):
    - If the SKILL.md frontmatter has `script.path` → fetch the script file from:
      `{baseUrl}/<name>/{script.path}`
      Create subdirectories (e.g., `scripts/`) as needed.
    - If the skill has a `references/` directory mentioned → fetch those files too.
    - If the skill has an `assets/` directory mentioned → fetch those files too.
 
-6. **Parse SKILL.md frontmatter** and check requirements:
+8. **Parse SKILL.md frontmatter** and check requirements:
 
    #### a. Environment Variables (if `env:` is present)
 
@@ -169,7 +170,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
         1. Yes, overwrite
         2. No, keep existing
         If "No" → skip MCP configuration but still complete installation
-   3. Use the values already collected in step 6.a for each env var in the skill's `env`
+   3. Use the values already collected in step 8.a for each env var in the skill's `env`
       array (do not ask again).
    4. Add to `mcpServers`:
       ```json
@@ -187,7 +188,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
    1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
    2. Check for `server_name` conflict (same as stdio above)
-   3. Use the values already collected in step 6.a for each env var in the skill's `env`
+   3. Use the values already collected in step 8.a for each env var in the skill's `env`
       array (do not ask again).
    4. Build the mcpServers entry:
       - Start with `{ "type": "http", "url": "{url}" }`
@@ -208,7 +209,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
    #### d. Script Setup (if `type: script` or `type: hybrid`)
 
    1. Verify the script file exists at `skills/<name>/{script.path}`
-      - If missing and wasn't fetched in step 5 → **ERROR**: "Script file not found. Installation may be incomplete."
+      - If missing and wasn't fetched in step 7 → **ERROR**: "Script file not found. Installation may be incomplete."
    2. If the skill lists dependencies in `script.dependencies`:
       - For `runtime: node` → run: `npm install {packages}`
       - For `runtime: python` → run: `pip install {packages}`
@@ -219,7 +220,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
    No additional setup needed. The skill is fully defined by its SKILL.md instructions.
 
-7. **Confirm installation**:
+9. **Confirm installation**:
    "✅ {name} installed! Crews can now use `{name}` in their skills list."
 
 ### 3. Create a Custom Skill
@@ -300,7 +301,7 @@ before the pipeline begins (fail fast).
    d. **Verify env vars** (if `env:` is present):
       - Check each variable in `.env`
       - If any are missing → ask the user conversationally, right here in chat, the same
-        way as Operation 2, step 6.a (never point them to the `.env` file to edit it
+        way as Operation 2, step 8.a (never point them to the `.env` file to edit it
         themselves). If they provide a value, write it to `.env` and continue. If they
         skip, warn: "⚠️ Skill '{skill}' is missing environment variable(s): {list}. It may
         not work correctly." — but do NOT block pipeline execution either way.