@aiwg/cli 2026.10.1 → 2026.10.4

package/tools/_resolve-impl.mjs

@@ -20,7 +20,7 @@ function findPackageRoot(callerUrl) {
     dir = parent;
   }
 
-  throw new Error(`Could not locate AIWG package root from ${callerUrl}`);
+  throw Object.assign(new Error(`Could not locate AIWG package root from ${callerUrl}`), { code: 'AIWG_PACKAGE_ROOT_MISSING' });
 }
 
 function candidatesFor(root, relativeFromSrc, base) {
@@ -46,6 +46,43 @@ 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 shipped relative import without exceptions.
+ *
+ * Directories `package.json`'s `files` excludes from the npm package
+ * (`tools/benchmarks/`, `tools/ci/`, `tools/contrib/`,
+ * `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).
+ *
+ * Decision study/replay scripts, experiments, OMP conformance probes, the
+ * desktop issuer qualification, and repository testing scripts are also
+ * excluded: they require checkout fixtures, development dependencies, or
+ * unshipped application code and have no installed CLI callers. Keep those
+ * scripts in the repository rather than adapting them for installation.
+ *
+ * `tools/docker/container-manager.mjs` and `Dockerfile.daemon` are shipped
+ * exceptions to the Docker directory exclusion: `aiwg daemon start --docker`
+ * needs both. The manager uses this resolver for its implementation import.
  */
 export function resolveImpl(callerUrl, relativeFromSrc) {
   const root = findPackageRoot(callerUrl);
@@ -65,7 +102,7 @@ export function resolveImpl(callerUrl, relativeFromSrc) {
   const attempted = order
     .flatMap((base) => candidatesFor(root, relativeFromSrc, base))
     .join(', ');
-  throw new Error(`Could not resolve ${relativeFromSrc}; attempted: ${attempted}`);
+  throw Object.assign(new Error(`Could not resolve ${relativeFromSrc}; attempted: ${attempted}`), { code: 'AIWG_IMPLEMENTATION_MISSING' });
 }
 
 export async function importImpl(callerUrl, relativeFromSrc) {

package/tools/agents/deploy-agents.mjs

@@ -11,13 +11,17 @@
  * 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
  *   --deploy-rules           Deploy rules in addition to agents
  *   --commands-only          Deploy only commands (skip agents)
  *   --skills-only            Deploy only skills (skip agents)
- *   --rules-only             Deploy only rules (skip agents)
+ *   --strict                 Fail startup budget overruns before deployment promotion
+  --report-only            Warn on startup budget overruns (migration default; CI remains strict)
+  --rules-only             Deploy only rules (skip agents)
  *   --dry-run                Show what would be deployed without writing
  *   --force                  Overwrite existing files
  *   --provider <name>        Target provider: antigravity (agy), claude (default), openai, codex, cursor, opencode, copilot, factory, grokbot, grok-build, muse, pi, omp, deepseek-harness (dsh), warp, devin, hermes, openhuman, or openclaw
@@ -187,7 +191,7 @@ function uniquePaths(paths) {
   return [...new Set(paths.filter(Boolean))];
 }
 
-function collectMirrorSkillDirs(srcRoot, mode) {
+export function collectMirrorSkillDirs(srcRoot, mode, providerName) {
   const dirs = [];
 
   const directSkillsDir = path.join(srcRoot, 'skills');
@@ -206,7 +210,14 @@ function collectMirrorSkillDirs(srcRoot, mode) {
     });
     dirs.push(...artifacts.skills);
 
-    if (mode === 'all') {
+    // Pi's provider collector already deploys all eligible addon skills for
+    // every root framework mode. Mirror the command-shaped addon skills in
+    // that same root pass so `aiwg use` does not need to repeat the entire
+    // deployment once per addon merely to produce these wrappers. Keep addon
+    // skills after framework skills: this preserves the existing per-addon
+    // winner when a framework and addon expose the same command name.
+    if (mode === 'all'
+      || (providerName === 'pi' && ['general', 'sdlc', 'both'].includes(mode))) {
       dirs.push(...getAddonSkillDirs(srcRoot));
     }
   }
@@ -292,7 +303,7 @@ function mirrorSkillsAsCommands(provider, target, srcRoot, opts) {
   const targetDir = resolveCommandMirrorDir(provider, target);
   if (!targetDir) return 0;
 
-  const skillDirs = collectMirrorSkillDirs(srcRoot, opts.mode)
+  const skillDirs = collectMirrorSkillDirs(srcRoot, opts.mode, provider.name)
     .filter((dir) => shouldMirrorCommandSkill(provider.name, path.basename(dir)));
 
   if (skillDirs.length === 0) return 0;
@@ -472,10 +483,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,
@@ -495,6 +506,8 @@ function parseArgs() {
     commandsOnly: false,
     skillsOnly: false,
     rulesOnly: false,
+    strict: false,
+    reportOnly: true,
     kernelOnly: false,
     filter: null,           // Glob pattern for agent names
     filterRole: null,       // Filter by role: reasoning|coding|efficiency
@@ -521,6 +534,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();
@@ -538,6 +559,9 @@ function parseArgs() {
     else if (a === '--commands-only') cfg.commandsOnly = true;
     else if (a === '--skills-only') cfg.skillsOnly = true;
     else if (a === '--rules-only') cfg.rulesOnly = true;
+    else if (a === '--strict') { cfg.strict = true; cfg.reportOnly = false; }
+    else if (a === '--allow-over-budget') cfg.allowOverBudget = true;
+    else if (a === '--report-only') cfg.reportOnly = true;
     else if (a === '--kernel-only') cfg.kernelOnly = true;
     else if (a === '--deploy-behaviors') cfg.deployBehaviors = true;
     else if (a === '--filter' && args[i + 1]) cfg.filter = args[++i];
@@ -577,6 +601,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
@@ -920,8 +946,8 @@ async function promptCommandsMigration(cfg, provider, targetDir) {
 // Main Entry Point
 // ============================================================================
 
-export async function main() {
-  const cfg = parseArgs();
+export async function main(args = process.argv.slice(2), internal = {}) {
+  const cfg = parseArgs(args);
 
   // Resolve source directory (default to repo root relative to this script)
   const __filename = fileURLToPath(import.meta.url);
@@ -1000,6 +1026,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,
@@ -1020,6 +1047,9 @@ export async function main() {
     commandsOnly: cfg.commandsOnly,
     skillsOnly: cfg.skillsOnly || cfg.kernelOnly,
     rulesOnly: cfg.rulesOnly,
+    strict: cfg.strict,
+    reportOnly: cfg.reportOnly,
+    allowOverBudget: cfg.allowOverBudget === true,
     kernelOnly: cfg.kernelOnly,
     filter: cfg.filter,
     filterRole: cfg.filterRole,
@@ -1043,31 +1073,41 @@ export async function main() {
     deployVersion: cfg.deployVersion || getDeployVersion(srcRoot),
     deploySource: cfg.deploySource || 'bundled',
   };
+  const { isRuleDeploymentPreparationActive } = await import('./providers/rule-delivery.mjs');
+  const preparationActive = isRuleDeploymentPreparationActive();
 
   // Commands → Skills migration: prompt then delete the commands directory
   // so stale command files don't create duplicates in the provider TUI.
-  if (!cfg.dryRun && !cfg.skipCommandsMigration) {
-    const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target);
-    if (doMigrate) {
+  if (!preparationActive && !internal.finalizeOnly) {
+    if (!cfg.dryRun && !cfg.skipCommandsMigration) {
+      const doMigrate = await promptCommandsMigration(cfg, provider, cfg.target);
+      if (doMigrate) {
+        const commandsRelPath = provider.paths?.commands;
+        if (commandsRelPath) {
+          migrateCommandsDirectory(path.join(cfg.target, commandsRelPath), opts);
+        }
+      } else {
+        // User said no — flip the flag so the provider knows to emit the duplicate warning
+        opts.skipCommandsMigration = true;
+      }
+    } else if (cfg.skipCommandsMigration) {
+      // Flag was passed explicitly — emit the duplicate warning now via a dry migration call
       const commandsRelPath = provider.paths?.commands;
-      if (commandsRelPath) {
+      if (commandsRelPath && !provider.capabilities?.homeDirectoryDeploy) {
         migrateCommandsDirectory(path.join(cfg.target, commandsRelPath), opts);
       }
-    } else {
-      // User said no — flip the flag so the provider knows to emit the duplicate warning
-      opts.skipCommandsMigration = true;
-    }
-  } else if (cfg.skipCommandsMigration) {
-    // Flag was passed explicitly — emit the duplicate warning now via a dry migration call
-    const commandsRelPath = provider.paths?.commands;
-    if (commandsRelPath && !provider.capabilities?.homeDirectoryDeploy) {
-      migrateCommandsDirectory(path.join(cfg.target, commandsRelPath), opts);
     }
   }
 
+  // Concurrent deployment runs this parent-owned preflight before any child
+  // snapshots its inputs. Migration can remove a provider command tree, so it
+  // must remain on the same side of the transaction boundary as serial deploy.
+  if (internal.preflightOnly) return;
+
   // Delegate to provider
   try {
-    await provider.deploy(opts);
+    if (!internal.finalizeOnly) await provider.deploy(opts);
+    if (preparationActive) return;
 
     const mirroredCommandCount = mirrorSkillsAsCommands(provider, cfg.target, srcRoot, opts);
     if (mirroredCommandCount > 0 && !cfg.quiet) {
@@ -1078,7 +1118,7 @@ export async function main() {
     // or removed (the flat-file analogue of the skills holistic prune). #1627.
     pruneStaleAiwgArtifacts(provider, cfg.target, srcRoot, opts, cfg.source);
 
-    if (!opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly) {
+    if (!['claude', 'codex', 'cursor', 'hermes', 'warp', 'openclaw'].includes(provider.name) && !opts.commandsOnly && !opts.skillsOnly && !opts.rulesOnly) {
       const behaviorDirs = collectBehaviorDirs(srcRoot);
       const behaviorCount = deployEmulatedBehaviors(behaviorDirs, provider.name, cfg.target, opts);
       if (behaviorCount > 0 && !cfg.quiet) {
@@ -1093,6 +1133,7 @@ export async function main() {
 
     if (!cfg.quiet) console.log(`\n=== Deployment complete ===\n`);
   } catch (err) {
+    if (preparationActive || internal.finalizeOnly) throw err;
     console.error(`\nDeployment failed:`, err.message);
     if (cfg.dryRun) {
       console.error('(dry-run mode - no files were modified)');