@aiwg/cli 2026.10.0 → 2026.10.3

package/tools/_resolve-impl.mjs

@@ -46,6 +46,45 @@ function resolveCandidate(root, relativeFromSrc, base) {
  *
  * Prefers dist/src/ when present. Set AIWG_RESOLVE_IMPL_FROM=dist or src to
  * force a side during CI/package-layout checks.
+ *
+ * ## Why a tools/ script that imports src/ needs this (#3062)
+ *
+ * The npm package ships the `tools/` tree (with maintainer-only exceptions
+ * below) and `dist/src/`; it does not ship `src/` itself (see `files` in
+ * package.json). A script under `tools/` that imports `../../src/<module>`
+ * directly by relative path works from a git checkout (`src/` exists
+ * there) but throws `ERR_MODULE_NOT_FOUND` once installed from npm, where
+ * only `dist/src/<module>` exists. Any shipped `.mjs` file under `tools/`
+ * or `bin/` that needs something under `src/` must resolve it through
+ * `importImpl(import.meta.url, '<module-path-relative-to-src>')` instead of
+ * a literal relative import, so it finds `dist/src/` when installed and
+ * `src/` in a checkout. `test/integration/tools-packed-relative-imports.test.ts`
+ * guards this for every relative import already known to resolve.
+ *
+ * Directories `package.json`'s `files` excludes from the npm package
+ * (`tools/benchmarks/`, `tools/ci/`, `tools/contrib/`, `tools/docker/`,
+ * `tools/eval/`, `tools/lint/` other than its listed exceptions,
+ * `tools/manifest/` other than its listed exception, `tools/qualification/`,
+ * and `tools/release/`) are maintainer/CI-only: they never run from an
+ * installed package, so a literal `../../src/<module>` import there is
+ * fine and does not need `importImpl`. Keep that distinction explicit at
+ * each such import site rather than silently mixing styles within one
+ * shipped-vs-not-shipped directory. `tools/benchmarks/` and
+ * `tools/qualification/` were excluded specifically because nothing
+ * shipped ever referenced them (#3062 B/C finding 2) — removing them
+ * also trims install size (#3075).
+ *
+ * `.ts` files directly under `tools/**` that remain shipped (e.g. under
+ * `tools/decision/`, `tools/experiments/`) are a separate, still-open
+ * case: they are only ever run via `tsx` through an `npm run` script in a
+ * checkout (there is no compile step that makes them directly
+ * `node`-executable), so they also keep literal `src/**` imports — there
+ * is no installed-package code path that reaches them to break. This is
+ * pre-existing, documented debt (see the baseline in
+ * `test/integration/tools-packed-relative-imports.test.ts`), not a
+ * recommendation to add more of it: a new shipped `.ts` tool should
+ * resolve through `importImpl` like everything else unless it has the
+ * same checkout-only justification.
  */
 export function resolveImpl(callerUrl, relativeFromSrc) {
   const root = findPackageRoot(callerUrl);

package/tools/agents/deploy-agents.mjs

@@ -11,6 +11,8 @@
  * Options:
  *   --source <path>          Source directory (defaults to repo root)
  *   --target <path>          Target directory (defaults to cwd)
+ *   --scope <user|project>   Deployment scope (default: project)
+ *   --user                  Shorthand for --scope user
  *   --mode <type>            Deployment mode: general, sdlc, marketing (alias: mmk), media-curator, research, both, or all (default)
  *   --deploy-commands        Deploy commands in addition to agents
  *   --deploy-skills          Deploy skills in addition to agents
@@ -472,10 +474,10 @@ function pruneStaleAiwgArtifacts(provider, target, srcRoot, opts, explicitSource
 // Argument Parsing
 // ============================================================================
 
-function parseArgs() {
-  const args = process.argv.slice(2);
+export function parseArgs(args = process.argv.slice(2)) {
   const cfg = {
     source: null,
+    userScope: false,
     target: process.cwd(),
     mode: 'all',  // 'general', 'sdlc', 'marketing', 'media-curator', 'research', 'both' (legacy), or 'all'
     dryRun: false,
@@ -521,6 +523,14 @@ function parseArgs() {
     if (a === '--source' && args[i + 1]) cfg.source = path.resolve(args[++i]);
     else if (a === '--target' && args[i + 1]) cfg.target = path.resolve(args[++i]);
     else if (a === '--mode' && args[i + 1]) cfg.mode = String(args[++i]).toLowerCase();
+    else if (a === '--scope') {
+      const scope = args[++i];
+      if (scope !== 'user' && scope !== 'project') {
+        throw new Error(`--scope expected 'user' or 'project', got '${scope ?? '(missing)'}'`);
+      }
+      cfg.userScope = scope === 'user';
+    }
+    else if (a === '--user') cfg.userScope = true;
     else if (a === '--dry-run') cfg.dryRun = true;
     else if (a === '--force') cfg.force = true;
     else if ((a === '--provider' || a === '--platform') && args[i + 1]) cfg.provider = String(args[++i]).toLowerCase();
@@ -577,6 +587,8 @@ Usage:
 Options:
   --source <path>          Source directory (defaults to repo root)
   --target <path>          Target directory (defaults to cwd)
+  --scope <user|project>   Deployment scope (default: project)
+  --user                  Shorthand for --scope user
   --mode <type>            Deployment mode: general, sdlc, marketing (alias: mmk), media-curator, research, both, or all (default)
   --deploy-commands        Deploy commands in addition to agents
   --deploy-skills          Deploy skills in addition to agents
@@ -1000,6 +1012,7 @@ export async function main() {
   const opts = {
     srcRoot,
     target: cfg.target,
+    ...(cfg.userScope ? { userScope: true } : {}),
     mode: cfg.mode,
     // Provider aliases are selectors, not artifact identities. Passing the
     // canonical id keeps generated frontmatter byte-identical for devin,

package/tools/agents/providers/base.mjs

@@ -11,10 +11,13 @@
 import realFs from 'fs';
 import path from 'path';
 import os from 'os';
+import yaml from 'yaml';
 import { classifyModelRole } from './model-role.mjs';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
-import { execSync as nodeExecSync } from 'child_process';
+import { importImpl } from '../../_resolve-impl.mjs';
+
+const { boundedExecFileSync } = await importImpl(import.meta.url, 'process/bounded-child-process.mjs');
 
 // Use graceful-fs to prevent EMFILE crashes on systems with low ulimit.
 // graceful-fs queues open() calls when FD pressure is detected and retries
@@ -376,41 +379,38 @@ const PROVIDER_TO_PLATFORM = {
 
 /**
  * Parse the platforms: field from a SKILL.md frontmatter block.
- * Handles both inline array (platforms: [a, b]) and multi-line list formats.
- * Returns null if no platforms field is present (= deploy to all providers).
- * Returns an empty array only if the field is explicitly empty.
+ * Accepts a string or a list of strings; all alone means unrestricted.
+ * Returns null if platforms is missing, or no frontmatter is present.
+ * Returns an empty array for malformed frontmatter or invalid platforms.
  */
 export function parseSkillPlatforms(content) {
-  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!fmMatch) return null;
-
-  const fm = fmMatch[1];
-
-  // Inline array: platforms: [claude-code, codex] or platforms: [all]
-  const inlineMatch = fm.match(/^platforms:\s*\[([^\]]*)\]/m);
-  if (inlineMatch) {
-    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
-    if (items.length === 0 || (items.length === 1 && items[0] === 'all')) return null;
-    return items;
+  // A leading UTF-8 BOM must not hide the frontmatter (and its restrictions).
+  if (content.charCodeAt(0) === 0xfeff) content = content.slice(1);
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m);
+  if (!fmMatch || fmMatch.index !== 0) {
+    return /^---[ \t]*(?:\r?\n|$)/.test(content) ? [] : null;
   }
 
-  // Multi-line list:
-  //   platforms:
-  //     - claude-code
-  //     - hermes
-  const multiMatch = fm.match(/^platforms:\s*\n((?:[ \t]+-[ \t]+\S[^\n]*\n?)+)/m);
-  if (multiMatch) {
-    const items = multiMatch[1]
-      .split('\n')
-      .map(line => line.match(/^[ \t]+-[ \t]+(\S+)/)?.[1])
-      .filter(Boolean);
-    return items.length > 0 ? items : null;
+  let metadata;
+  try {
+    const document = yaml.parseDocument(fmMatch[1]);
+    if (document.errors.length > 0) return [];
+    if (!document.contents) return null; // Empty frontmatter has no restrictions.
+    metadata = document.toJS();
+  } catch {
+    return [];
   }
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) return [];
+  // The yaml package leaves merge keys unresolved, so platforms could arrive only
+  // through `<<`; without an explicit key that is ambiguous, so fail closed.
+  if (!Object.hasOwn(metadata, 'platforms')) return Object.hasOwn(metadata, '<<') ? [] : null;
 
-  // platforms: key present but empty
-  if (/^platforms:\s*$/m.test(fm)) return null;
-
-  return null; // Field absent = deploy to all
+  const platforms = metadata.platforms;
+  const items = typeof platforms === 'string' ? [platforms] : platforms;
+  if (!Array.isArray(items) || !items.every(item => typeof item === 'string')) return [];
+  const normalized = items.map(item => item.trim());
+  if (normalized.some(item => !item)) return [];
+  return normalized.length === 1 && normalized[0] === 'all' ? null : normalized;
 }
 
 /**
@@ -1363,13 +1363,13 @@ export function computeAllArtifactBasenames(srcRoot, type) {
     // Soul companions live alongside agents and are deployed with them —
     // keep their stems in the desired set so the prune never removes them.
     add(frameworkArtifacts.souls || []);
-    add(getAddonAgentFiles(aiwgRoot));
+    add(getAddonAgentFiles(aiwgRoot, [], { includeExplicit: true }));
   } else if (type === 'commands') {
     add(frameworkArtifacts.commands);
-    add(getAddonCommandFiles(aiwgRoot));
+    add(getAddonCommandFiles(aiwgRoot, [], { includeExplicit: true }));
   } else if (type === 'rules') {
     add(frameworkArtifacts.rules);
-    add(getAddonRuleFiles(aiwgRoot));
+    add(getAddonRuleFiles(aiwgRoot, [], { includeExplicit: true }));
   }
 
   return stems;
@@ -1811,7 +1811,7 @@ export function buildRemotesTopologyBlock(targetDir) {
 
   function getUrl(remote) {
     try {
-      return nodeExecSync(`git -C ${JSON.stringify(targetDir)} remote get-url ${JSON.stringify(remote)}`, {
+      return boundedExecFileSync('git', ['-C', targetDir, 'remote', 'get-url', '--', remote], 'quick', {
         stdio: ['ignore', 'pipe', 'ignore'],
         encoding: 'utf8',
       }).trim();
@@ -2264,9 +2264,10 @@ export function collectFrameworkArtifacts(srcRoot, mode, options = {}) {
 /**
  * Discover all addons in the agentic/code/addons directory
  * @param {string} srcRoot - Source root directory
+ * @param {{includeExplicit?: boolean}} [options] - includeExplicit also returns explicitInstall addons
  * @returns {Array<{name: string, path: string, manifest: object}>} - Array of addon info
  */
-export function discoverAddons(srcRoot) {
+export function discoverAddons(srcRoot, { includeExplicit = false } = {}) {
   const addonsDir = path.join(srcRoot, 'agentic', 'code', 'addons');
   if (!fs.existsSync(addonsDir)) return [];
 
@@ -2290,7 +2291,9 @@ export function discoverAddons(srcRoot) {
     if (manifest.devOnly === true) continue;
     // explicitInstall addons deploy only when named (`aiwg use <addon>`), never
     // as part of a framework or `all` bulk deploy (#2641).
-    if (manifest.explicitInstall === true) continue;
+    // The stale-artifact prune passes includeExplicit so a named install's own
+    // files stay in its desired set and are not deleted right after deployment.
+    if (manifest.explicitInstall === true && !includeExplicit) continue;
 
     addons.push({
       name: entry.name,
@@ -2308,8 +2311,8 @@ export function discoverAddons(srcRoot) {
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of agent file paths
  */
-export function getAddonAgentFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonAgentFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {
@@ -2330,8 +2333,8 @@ export function getAddonAgentFiles(srcRoot, excludeAddons = []) {
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of command file paths
  */
-export function getAddonCommandFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonCommandFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {
@@ -2347,7 +2350,7 @@ export function getAddonCommandFiles(srcRoot, excludeAddons = []) {
 }
 
 /**
- * Get all skill directories from all addons
+ * Get skill directories from a direct addon/framework source or all addons
  * @param {string} srcRoot - Source root directory
  * @param {string[]} excludeAddons - Addon names to exclude (default: none)
  * @returns {string[]} - Array of skill directory paths
@@ -2355,6 +2358,8 @@ export function getAddonCommandFiles(srcRoot, excludeAddons = []) {
 export function getAddonSkillDirs(srcRoot, excludeAddons = []) {
   const addons = discoverAddons(srcRoot);
   const dirs = [];
+  const directDir = getDirectSourceDir(srcRoot, excludeAddons);
+  if (directDir) dirs.push(...listSkillDirs(directDir));
 
   for (const addon of addons) {
     if (excludeAddons.includes(addon.name)) continue;
@@ -2368,6 +2373,21 @@ export function getAddonSkillDirs(srcRoot, excludeAddons = []) {
   return dirs;
 }
 
+// `aiwg use <addon>` passes the component itself as --source. Keep bulk
+// repository discovery unchanged, even if the repo has a top-level skills/.
+function getDirectSourceDir(srcRoot, excludeAddons) {
+  if (fs.existsSync(path.join(srcRoot, 'agentic', 'code')) ||
+      excludeAddons.includes(path.basename(path.resolve(srcRoot)))) return null;
+  const dir = path.join(srcRoot, 'skills');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null;
+  const relative = path.relative(fs.realpathSync(srcRoot), fs.realpathSync(dir));
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    console.warn(`Warning: Skipping direct skills directory ${dir}: resolves outside source root ${srcRoot}`);
+    return null;
+  }
+  return dir;
+}
+
 /**
  * Get all rule files from all addons
  * @param {string} srcRoot - Source root directory
@@ -2651,8 +2671,8 @@ export function writeOnDemandRuleIndex(destDir, onDemandFiles, opts = {}) {
   return names.length + demotedNames.length;
 }
 
-export function getAddonRuleFiles(srcRoot, excludeAddons = []) {
-  const addons = discoverAddons(srcRoot);
+export function getAddonRuleFiles(srcRoot, excludeAddons = [], options = {}) {
+  const addons = discoverAddons(srcRoot, options);
   const files = [];
 
   for (const addon of addons) {

package/tools/agents/providers/grokbot.mjs

@@ -1,5 +1,5 @@
 /**
- * Grok Bot provider (experimental).
+ * Grok Bot provider (stable).
  *
  * Discover-first project bridge + fail-closed user skill root.
  * Never targets `.cursor/**` or invents `~/.grokbot`.
@@ -127,21 +127,18 @@ export function deployRules() {
 }
 
 /**
- * Deploy skills only when AIWG_GROKBOT_SKILLS_DIR is configured.
+ * Deploy skills only at user scope with AIWG_GROKBOT_SKILLS_DIR configured.
  * Kernel → configured root; standard → index/discovery unless --copy-all
  * (then `<root>/.aiwg/skills`).
  */
 export function deploySkills(skillDirs, targetDir, opts = {}) {
-  const root = resolveGrokbotSkillsDir(opts.env || process.env);
-  if (!root) {
+  if (opts.userScope !== true && opts.scope !== 'user') {
     if (!opts.quiet) {
-      console.log(
-        `\n  Grok Bot: skipping native skill copy (${SKILLS_DIR_ENV} unset). ` +
-          'Skills remain available via aiwg discover / aiwg show.',
-      );
+      console.log('\n  Grok Bot: project bridge only; native skills require --scope user.');
     }
     return 0;
   }
+  const root = assertUserScopeConfigured(opts);
 
   if (root.includes(`${path.sep}.cursor${path.sep}`) || root.endsWith(`${path.sep}.cursor`) || root.includes('/.cursor/') || root.endsWith('/.cursor')) {
     throw new Error(
@@ -178,14 +175,14 @@ export async function postDeploy(targetDir, opts = {}) {
   }
   if (!opts.quiet) {
     const root = resolveGrokbotSkillsDir(opts.env || process.env);
-    if (root) {
+    if (root && (opts.userScope === true || opts.scope === 'user')) {
       console.log(
         'Grok Bot: after deploy, start a new agent chat or re-read skills. ' +
           'Live refresh is not claimed until product behavior is verified.',
       );
     } else {
       console.log(
-        `Grok Bot: project bridge only. Set ${SKILLS_DIR_ENV} for user-scope skill deploy.`,
+        `Grok Bot: project bridge only. Use --scope user with ${SKILLS_DIR_ENV} for native skills.`,
       );
     }
   }
@@ -197,7 +194,7 @@ export function getFileExtension() {
 
 /**
  * Assert user-scope is allowed. Called when the orchestrator is mirroring
- * to user scope or when opts.scope === 'user'.
+ * to user scope or when opts.userScope === true / opts.scope === 'user'.
  */
 export function assertUserScopeConfigured(opts = {}) {
   const root = resolveGrokbotSkillsDir(opts.env || process.env);
@@ -227,7 +224,9 @@ export async function deploy(opts = {}) {
     console.log(`Mode: ${mode}`);
     const root = resolveGrokbotSkillsDir(opts.env || process.env);
     console.log(
-      `Skills root: ${root || `(unset — set ${SKILLS_DIR_ENV} for user-scope writes)`}`,
+      (opts.userScope === true || scope === 'user')
+        ? `User skills root: ${root || `(unset — set ${SKILLS_DIR_ENV})`}`
+        : 'Skills: project bridge only (no native skill writes)',
     );
     if (opts.dryRun) console.log('Dry-run: no filesystem mutations');
   }

package/tools/agents/providers/hermes.mjs

@@ -26,7 +26,6 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import {
   ensureDir,
   listMdFiles,
-  listSkillDirs,
   deploySkillDir,
   deploySkillsWithKernelRouting,
   isKernelSkill,
@@ -466,7 +465,7 @@ export async function deploy(opts) {
   if ((shouldDeploySkills || skillsOnly) && !opts.commandsOnly && !opts.rulesOnly) {
     const allSkillDirs = [];
 
-    // Addon skills (aiwg-utils, ralph, etc.)
+    // Addon skills, including a direct addon source (#2873, #3035).
     allSkillDirs.push(...getAddonSkillDirs(srcRoot));
 
     // Framework skills
@@ -665,7 +664,11 @@ export function updateBundledManifest(kernelSkillNames, opts) {
  */
 export function migrateLegacySkillPath(opts) {
   const { dryRun, quiet } = opts;
-  const legacyPath = path.join(os.homedir(), '.hermes', '.aiwg', 'skills');
+  // Resolve through the same HERMES_HOME contract as every other path in
+  // this provider (env var first, platform default otherwise): with
+  // HERMES_HOME set, the legacy tree lives under that root — never under
+  // the process home directory.
+  const legacyPath = path.join(getHermesHome(), '.aiwg', 'skills');
   const newPath = paths.skills;
 
   let legacyExists = false;

package/tools/agents/providers/omp.mjs

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import YAML from 'yaml';
-import { resolveOmpPaths } from '../../../src/providers/omp-paths.mjs';
+import { importImpl } from '../../_resolve-impl.mjs';
 import { collectFrameworkArtifacts, getAddonFiles, isKernelSkill, listMdFiles, listSkillDirs, normalizeDeploymentMode, resolveAiwgRoot } from './base.mjs';
 export const name = 'omp';
 export const aliases = ['oh-my-pi'];
@@ -18,7 +18,10 @@ function parse(content) {
 }
 const render = (metadata, body) => `---\n${YAML.stringify(metadata)}---\n\n${body.trim()}\n`;
 function diagnostic(opts, message) { opts.diagnostics?.push(message); if (!opts.quiet) console.warn(`OMP: ${message}`); }
-import { transformAgent, mapModel } from '../../../src/providers/omp-agent.mjs';
+// Resolved through the shared resolver: an installed package ships these
+// modules under dist/src, not src, so a literal path into src fails there.
+const { resolveOmpPaths } = await importImpl(import.meta.url, 'providers/omp-paths.mjs');
+const { transformAgent, mapModel } = await importImpl(import.meta.url, 'providers/omp-agent.mjs');
 export { transformAgent, mapModel };
 const array = value => Array.isArray(value) ? value : typeof value === 'string' ? value.split(',').map(s => s.trim()).filter(Boolean) : [];
 export function transformCommand(src, content, opts = {}) {

package/tools/agents/providers/openclaw-translator.mjs

@@ -120,6 +120,20 @@ function parseBehaviorFrontmatter(content) {
   return frontmatter;
 }
 
+/** Encode a complete YAML double-quoted scalar. */
+function yamlString(value) {
+  return JSON.stringify(value)
+    .replace(/\u0085/g, '\\u0085')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/** Keep metadata within a single line or block comment. */
+function escapeComment(value) {
+  return String(value).replace(/\*\//g, '* /')
+    .replace(/[\r\n\u2028\u2029]/g, (char) => '\\u' + char.charCodeAt(0).toString(16).padStart(4, '0'));
+}
+
 /**
  * Render the HOOK.md content for OpenClaw's hook loader.
  *
@@ -133,15 +147,15 @@ function parseBehaviorFrontmatter(content) {
 export function renderHookMd(behavior) {
   const events = Object.keys(behavior.hooks || {});
   const eventsList = events.length > 0
-    ? events.map((e) => `  - ${e}`).join('\n')
+    ? events.map((e) => `  - ${yamlString(e)}`).join('\n')
     : '  []';
 
-  const description = (behavior.description || '').replace(/"/g, '\\"').slice(0, 200);
+  const description = yamlString((behavior.description || '').slice(0, 200));
 
   return [
     '---',
-    `name: ${behavior.name}`,
-    `description: "${description}"`,
+    `name: ${yamlString(behavior.name)}`,
+    `description: ${description}`,
     'events:',
     eventsList,
     'handler: ./handler.js',
@@ -193,7 +207,7 @@ export function renderHandlerJs(behavior, scriptsRelDir = './scripts') {
 
   return `#!/usr/bin/env node
 // Generated by AIWG (PUW-008/PUW-009). Do not edit; regenerated on \`aiwg use\`.
-// Handler for OpenClaw hook \`${behavior.name}\`. Dispatches to scripts in
+// Handler for OpenClaw hook \`${escapeComment(behavior.name)}\`. Dispatches to scripts in
 // ./scripts/ based on the event delivered by OpenClaw's hook loader.
 //
 // Stdin contract (AIWG canonical, per ADR-3 §3):