@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
package/dist/cli.js CHANGED
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
- import { existsSync, realpathSync, readFileSync, openSync, closeSync } from 'fs';
3
- import { mkdir, mkdtemp, writeFile, readdir, rename, unlink, rmdir, rm, readFile, copyFile } from 'fs/promises';
2
+ import require$$1, { createHash as createHash$2, randomUUID } from 'crypto';
3
+ import { existsSync, readFileSync, realpathSync, openSync, closeSync } from 'fs';
4
+ import { readFile, lstat, readdir, rm, mkdir, writeFile, rename, realpath, rmdir, mkdtemp, unlink, appendFile } from 'fs/promises';
5
+ import { createRequire } from 'module';
4
6
  import path from 'path';
5
7
  import require$$7, { fileURLToPath, pathToFileURL } from 'url';
6
- import { execFileSync, spawn } from 'child_process';
7
- import require$$1, { randomUUID, createHash as createHash$2 } from 'crypto';
8
+ import { execFileSync, spawn, spawnSync } from 'child_process';
8
9
  import require$$3$1, { createConnection } from 'net';
9
- import { createRequire } from 'module';
10
10
  import require$$0$3 from 'events';
11
11
  import require$$1$1 from 'https';
12
12
  import require$$2$1 from 'http';
@@ -2370,21 +2370,1065 @@ var semver = {
2370
2370
  var semver$1 = /*@__PURE__*/getDefaultExportFromCjs(semver);
2371
2371
 
2372
2372
  /**
2373
- * Copyright (c) Meta Platforms, Inc. and affiliates.
2374
- *
2375
- * This source code is licensed under the MIT license found in the
2376
- * LICENSE file in the root directory of this source tree.
2373
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
2374
+ *
2375
+ * This source code is licensed under the MIT license found in the
2376
+ * LICENSE file in the root directory of this source tree.
2377
+ */
2378
+ function getUnsupportedNodeMessage(version, requiredRange) {
2379
+ if (semver$1.satisfies(version, requiredRange, { includePrerelease: true })) {
2380
+ return undefined;
2381
+ }
2382
+ return (`Unsupported Node.js version: ${version}. IWSDK requires Node ${requiredRange}. ` +
2383
+ 'Upgrade Node (for example with nvm or Volta) and retry.');
2384
+ }
2385
+
2386
+ const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
2387
+ const CLI_VERSION = "1.2.0-rc.0";
2388
+
2389
+ /**
2390
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
2391
+ *
2392
+ * This source code is licensed under the MIT license found in the
2393
+ * LICENSE file in the root directory of this source tree.
2394
+ */
2395
+ /** Same list as SUPPORTED_AI_TOOLS; test/agent-guidance.test.ts checks it. */
2396
+ const GUIDANCE_TOOLS = [
2397
+ 'claude',
2398
+ 'cursor',
2399
+ 'copilot',
2400
+ 'codex',
2401
+ 'opencode',
2402
+ ];
2403
+ // Hash and stamp format. Keep in sync with
2404
+ // packages/core/scripts/agent-guidance-format.mjs, which renders the files;
2405
+ // test/agent-guidance.test.ts checks both sides against a fresh render.
2406
+ const GUIDANCE_FORMAT = 1;
2407
+ const BLOCK_NAME = 'iwsdk-agent-guidance';
2408
+ const STAMP_LINE = /^<!-- iwsdk-agent-guidance version=(\S+) sha256=([0-9a-f]{64})(?: name=(\S+))? [^\n]*-->\r?\n?/mu;
2409
+ const BLOCK_PATTERN = new RegExp(`<!-- BEGIN ${BLOCK_NAME} version=(\\S+) sha256=([0-9a-f]{64}) -->\\n([\\s\\S]*?)<!-- END ${BLOCK_NAME} -->\\n?`, 'u');
2410
+ const BLOCK_BEGIN = new RegExp(`<!-- BEGIN ${BLOCK_NAME}\\b`, 'gu');
2411
+ const BLOCK_END = new RegExp(`<!-- END ${BLOCK_NAME} -->`, 'gu');
2412
+ // Releases before the managed block opened AGENTS.md and CLAUDE.md with this
2413
+ // heading ("# IWSDK Project" in 0.4, "# IWSDK project" later).
2414
+ const LEGACY_IWSDK_HEADING = /^# IWSDK (?:scoped )?project/iu;
2415
+ const SKILL_PERMISSION = /^Skill\((iwsdk-[^)]*)\)$/u;
2416
+ /** Files that operating systems and editors drop into folders; never hashed. */
2417
+ const JUNK_FILE = /^(?:\.DS_Store|Thumbs\.db|desktop\.ini)$|\.swp$|~$/u;
2418
+ // Same sentence as the top of agent-guidance/common/AGENTS.md in @iwsdk/core.
2419
+ const RETIRED_SURFACES_NOTICE = "IWSDK changes faster than model training data. GLXF scenes, the external 0.4 scene editor and its Vite plugin, and the UIKitML-compile and glTF-optimizer Vite plugins were removed in 0.5: scenes are native `*.iwsdk.scene.json` files edited in IWSDK's built-in editor, and `@iwsdk/vite-plugin-dev` is the only IWSDK Vite plugin.";
2420
+ class GuidanceSourceError extends Error {
2421
+ constructor(message, code) {
2422
+ super(message);
2423
+ this.code = code;
2424
+ this.name = 'GuidanceSourceError';
2425
+ }
2426
+ }
2427
+ function sha256(text) {
2428
+ return createHash$2('sha256').update(text).digest('hex');
2429
+ }
2430
+ function normalizeText(text) {
2431
+ return text.replace(/\r\n/gu, '\n');
2432
+ }
2433
+ function withTrailingNewline(text) {
2434
+ return text.endsWith('\n') ? text : `${text}\n`;
2435
+ }
2436
+ function stripStamp(text) {
2437
+ return normalizeText(text).replace(STAMP_LINE, '');
2438
+ }
2439
+ function readStamp(text) {
2440
+ const match = normalizeText(text).match(STAMP_LINE);
2441
+ return match ? { version: match[1], sha256: match[2], name: match[3] } : null;
2442
+ }
2443
+ function fileUnitHash(text) {
2444
+ return sha256(stripStamp(text));
2445
+ }
2446
+ function directoryUnitHash(files) {
2447
+ const hash = createHash$2('sha256');
2448
+ for (const [relativePath, contents] of [...files].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {
2449
+ const digest = typeof contents === 'string' ? fileUnitHash(contents) : sha256(contents);
2450
+ hash.update(`${relativePath}\0${digest}\n`);
2451
+ }
2452
+ return hash.digest('hex');
2453
+ }
2454
+ function blockUnitHash(body) {
2455
+ return sha256(withTrailingNewline(normalizeText(body)));
2456
+ }
2457
+ function isTextFile(name) {
2458
+ return !/\.(png|jpe?g|webp|gif|glb|mp3|ktx2)$/iu.test(name);
2459
+ }
2460
+ async function readTree(root, relative = '', files = new Map()) {
2461
+ for (const entry of await readdir(path.join(root, relative), {
2462
+ withFileTypes: true,
2463
+ })) {
2464
+ const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
2465
+ if (JUNK_FILE.test(entry.name)) {
2466
+ continue;
2467
+ }
2468
+ if (entry.isDirectory()) {
2469
+ await readTree(root, childRelative, files);
2470
+ }
2471
+ else if (entry.isFile()) {
2472
+ const contents = await readFile(path.join(root, childRelative));
2473
+ files.set(childRelative, isTextFile(entry.name) ? contents.toString('utf8') : contents);
2474
+ }
2475
+ }
2476
+ return files;
2477
+ }
2478
+ async function readTextIfExists(filePath) {
2479
+ try {
2480
+ return await readFile(filePath, 'utf8');
2481
+ }
2482
+ catch (error) {
2483
+ if (error.code === 'ENOENT') {
2484
+ return null;
2485
+ }
2486
+ throw error;
2487
+ }
2488
+ }
2489
+ function assertRelativeUnitPath(unitPath) {
2490
+ if (path.isAbsolute(unitPath) ||
2491
+ unitPath
2492
+ .split(/[\\/]/u)
2493
+ .some((segment) => segment === '..' || segment === '')) {
2494
+ throw new GuidanceSourceError(`Guidance manifest contains an unsafe path: ${unitPath}`, 'guidance_unavailable');
2495
+ }
2496
+ }
2497
+ async function loadGuidanceSource(root, origin = 'explicit') {
2498
+ const manifestPath = path.join(root, 'manifest.json');
2499
+ const raw = await readTextIfExists(manifestPath);
2500
+ if (raw == null) {
2501
+ throw new GuidanceSourceError(`No agent guidance manifest at ${manifestPath}`, 'guidance_unavailable');
2502
+ }
2503
+ let manifest;
2504
+ try {
2505
+ manifest = JSON.parse(raw);
2506
+ }
2507
+ catch {
2508
+ throw new GuidanceSourceError(`The agent guidance manifest at ${manifestPath} is not valid JSON. Reinstall IWSDK.`, 'guidance_unavailable');
2509
+ }
2510
+ if (manifest.format !== GUIDANCE_FORMAT) {
2511
+ throw new GuidanceSourceError(`Agent guidance format ${manifest.format} is not supported by this @iwsdk/cli (expects ${GUIDANCE_FORMAT}). Use the @iwsdk/cli release that matches @iwsdk/core.`, 'unsupported_guidance_format');
2512
+ }
2513
+ for (const unit of manifest.units) {
2514
+ assertRelativeUnitPath(unit.path);
2515
+ for (const file of unit.files ?? []) {
2516
+ assertRelativeUnitPath(file);
2517
+ }
2518
+ }
2519
+ return { root, manifest, origin };
2520
+ }
2521
+ function bundledGuidanceRoot() {
2522
+ return fileURLToPath(new URL('./agent-guidance/', import.meta.url));
2523
+ }
2524
+ /** Version of `@iwsdk/core` installed for the project, or null. */
2525
+ function readInstalledCoreVersion(projectRoot) {
2526
+ const packageJsonPath = resolveInstalledCorePackageJson(projectRoot);
2527
+ if (packageJsonPath == null) {
2528
+ return null;
2529
+ }
2530
+ try {
2531
+ return (JSON.parse(readFileSync(packageJsonPath, 'utf8')).version ?? null);
2532
+ }
2533
+ catch {
2534
+ return null;
2535
+ }
2536
+ }
2537
+ /**
2538
+ * The installed `@iwsdk/core/package.json`, looked up fresh each time. Node's
2539
+ * resolver caches paths per process, so after `pnpm install` re-points
2540
+ * node_modules/@iwsdk/core it would still return the old release.
2541
+ */
2542
+ function resolveInstalledCorePackageJson(projectRoot) {
2543
+ let current = path.resolve(projectRoot);
2544
+ while (true) {
2545
+ const candidate = path.join(current, 'node_modules', '@iwsdk', 'core', 'package.json');
2546
+ if (existsSync(candidate)) {
2547
+ return realpathSync(candidate);
2548
+ }
2549
+ const parent = path.dirname(current);
2550
+ if (parent === current) {
2551
+ break;
2552
+ }
2553
+ current = parent;
2554
+ }
2555
+ // Layouts without node_modules folders (Yarn Plug'n'Play).
2556
+ try {
2557
+ return createRequire(path.join(projectRoot, 'package.json')).resolve('@iwsdk/core/package.json');
2558
+ }
2559
+ catch {
2560
+ return null;
2561
+ }
2562
+ }
2563
+ /**
2564
+ * Guidance for a project: the copy shipped in its installed `@iwsdk/core`, so
2565
+ * it always matches the installed release. Before `@iwsdk/core` is installed,
2566
+ * the copy bundled with this CLI is used instead.
2567
+ */
2568
+ async function resolveProjectGuidance(projectRoot) {
2569
+ const corePackageJson = resolveInstalledCorePackageJson(projectRoot);
2570
+ if (corePackageJson != null) {
2571
+ const root = path.join(path.dirname(corePackageJson), 'dist', 'agent-guidance');
2572
+ if (!existsSync(path.join(root, 'manifest.json'))) {
2573
+ const version = readInstalledCoreVersion(projectRoot) ?? 'unknown';
2574
+ throw new GuidanceSourceError(`The installed @iwsdk/core ${version} predates bundled agent guidance. Upgrade IWSDK with \`npx @iwsdk/cli@latest upgrade\`.`, 'core_without_guidance');
2575
+ }
2576
+ return loadGuidanceSource(root, 'installed-core');
2577
+ }
2578
+ if (declaresCore(projectRoot)) {
2579
+ // Guidance from this CLI could belong to a different release than the
2580
+ // one the project declares; wait for the real one.
2581
+ throw new GuidanceSourceError(`package.json lists @iwsdk/core, but it is not installed in ${projectRoot}. Install the project's dependencies first, then run this command again.`, 'core_not_installed');
2582
+ }
2583
+ return loadGuidanceSource(bundledGuidanceRoot(), 'bundled-cli');
2584
+ }
2585
+ function declaresCore(projectRoot) {
2586
+ try {
2587
+ const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
2588
+ return ['dependencies', 'devDependencies', 'peerDependencies'].some((field) => {
2589
+ const dependencies = manifest[field];
2590
+ return (typeof dependencies === 'object' &&
2591
+ dependencies !== null &&
2592
+ '@iwsdk/core' in dependencies);
2593
+ });
2594
+ }
2595
+ catch {
2596
+ return false;
2597
+ }
2598
+ }
2599
+ function selectedUnits(manifest, tools) {
2600
+ return manifest.units.filter((unit) => unit.tools.some((tool) => tools.includes(tool)));
2601
+ }
2602
+ async function resolveLink(filePath) {
2603
+ try {
2604
+ return (await lstat(filePath)).isSymbolicLink()
2605
+ ? await realpath(filePath)
2606
+ : filePath;
2607
+ }
2608
+ catch {
2609
+ return filePath;
2610
+ }
2611
+ }
2612
+ /** Both paths name the same file once every link on the way is followed. */
2613
+ async function isSameFile(first, second) {
2614
+ try {
2615
+ return (await realpath(first)) === (await realpath(second));
2616
+ }
2617
+ catch {
2618
+ return false;
2619
+ }
2620
+ }
2621
+ /** Temporary siblings a sync left behind when it was killed mid-swap. */
2622
+ const TEMPORARY_SIBLING = /^\..+\.iwsdk-(?:new|old)-(\d+)-(\d+)$/u;
2623
+ /** A temporary sibling that a sync running right now may still need. */
2624
+ function isInUse(name) {
2625
+ const [, pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
2626
+ if (Date.now() - Number(createdAt) < 10 * 60_000) {
2627
+ return true;
2628
+ }
2629
+ try {
2630
+ process.kill(Number(pid), 0);
2631
+ return true;
2632
+ }
2633
+ catch (error) {
2634
+ // EPERM: the process exists but belongs to someone else.
2635
+ return error.code !== 'ESRCH';
2636
+ }
2637
+ }
2638
+ function temporarySibling(filePath, label) {
2639
+ return path.join(path.dirname(filePath), `.${path.basename(filePath)}.iwsdk-${label}-${process.pid}-${Date.now()}`);
2640
+ }
2641
+ function createWriter(projectRoot, dryRun) {
2642
+ return {
2643
+ dryRun,
2644
+ projectRoot,
2645
+ async write(relativePath, contents) {
2646
+ if (dryRun) {
2647
+ return;
2648
+ }
2649
+ // Write through a link (CLAUDE.md -> AGENTS.md is common), so the
2650
+ // rename replaces the file it points at, not the link itself.
2651
+ const filePath = await resolveLink(path.join(projectRoot, relativePath));
2652
+ await mkdir(path.dirname(filePath), { recursive: true });
2653
+ const staged = temporarySibling(filePath, 'new');
2654
+ try {
2655
+ await writeFile(staged, contents);
2656
+ await rename(staged, filePath);
2657
+ }
2658
+ finally {
2659
+ await rm(staged, { force: true });
2660
+ }
2661
+ },
2662
+ async replaceDirectory(relativePath, files) {
2663
+ if (dryRun) {
2664
+ return;
2665
+ }
2666
+ const target = path.join(projectRoot, relativePath);
2667
+ await mkdir(path.dirname(target), { recursive: true });
2668
+ const staged = temporarySibling(target, 'new');
2669
+ const previous = temporarySibling(target, 'old');
2670
+ try {
2671
+ for (const [file, contents] of files) {
2672
+ const filePath = path.join(staged, file);
2673
+ await mkdir(path.dirname(filePath), { recursive: true });
2674
+ await writeFile(filePath, contents);
2675
+ }
2676
+ const hadPrevious = existsSync(target);
2677
+ if (hadPrevious) {
2678
+ await rename(target, previous);
2679
+ }
2680
+ try {
2681
+ await rename(staged, target);
2682
+ }
2683
+ catch (error) {
2684
+ if (hadPrevious) {
2685
+ await rename(previous, target);
2686
+ }
2687
+ throw error;
2688
+ }
2689
+ }
2690
+ finally {
2691
+ await rm(staged, { recursive: true, force: true });
2692
+ await rm(previous, { recursive: true, force: true });
2693
+ }
2694
+ },
2695
+ async remove(relativePath) {
2696
+ if (dryRun) {
2697
+ return;
2698
+ }
2699
+ await rm(path.join(projectRoot, relativePath), {
2700
+ recursive: true,
2701
+ force: true,
2702
+ });
2703
+ await removeEmptyParents(projectRoot, path.dirname(relativePath));
2704
+ },
2705
+ };
2706
+ }
2707
+ async function removeEmptyParents(projectRoot, relativeDirectory) {
2708
+ let current = relativeDirectory;
2709
+ while (current && current !== '.') {
2710
+ try {
2711
+ await rmdir(path.join(projectRoot, current));
2712
+ }
2713
+ catch {
2714
+ return;
2715
+ }
2716
+ current = path.dirname(current);
2717
+ }
2718
+ }
2719
+ async function readSourceFile(source, relativePath) {
2720
+ return readFile(path.join(source.root, 'files', relativePath));
2721
+ }
2722
+ /** Text written back with the line endings the existing file used. */
2723
+ function withLineEndings(text, existing) {
2724
+ return existing.includes('\r\n') ? text.replace(/\r?\n/gu, '\r\n') : text;
2725
+ }
2726
+ function classify(localHash, targetHash, stamp, legacyHashes, manifestVersion) {
2727
+ if (targetHash !== undefined && localHash === targetHash) {
2728
+ return 'unchanged';
2729
+ }
2730
+ if (stamp) {
2731
+ if (stamp.sha256 !== localHash) {
2732
+ return 'modified';
2733
+ }
2734
+ // Written by a newer release than this guidance: an older CLI or core
2735
+ // must not roll it back.
2736
+ return semver$1.valid(stamp.version) &&
2737
+ semver$1.valid(manifestVersion) &&
2738
+ semver$1.gt(stamp.version, manifestVersion)
2739
+ ? 'newer'
2740
+ : 'managed';
2741
+ }
2742
+ return legacyHashes?.includes(localHash) ? 'legacy' : 'unmanaged';
2743
+ }
2744
+ function replacementResult(unit, ownership, force) {
2745
+ if (ownership === 'managed') {
2746
+ return { path: unit.path, kind: unit.kind, action: 'updated' };
2747
+ }
2748
+ if (ownership === 'legacy') {
2749
+ return {
2750
+ path: unit.path,
2751
+ kind: unit.kind,
2752
+ action: 'updated',
2753
+ reason: 'legacy',
2754
+ };
2755
+ }
2756
+ if (ownership === 'newer') {
2757
+ return {
2758
+ path: unit.path,
2759
+ kind: unit.kind,
2760
+ action: 'skipped',
2761
+ reason: 'newer',
2762
+ detail: 'Written by a newer IWSDK release; upgrade @iwsdk/core.',
2763
+ };
2764
+ }
2765
+ if (ownership === 'modified' || ownership === 'unmanaged') {
2766
+ return force
2767
+ ? {
2768
+ path: unit.path,
2769
+ kind: unit.kind,
2770
+ action: 'updated',
2771
+ reason: 'forced',
2772
+ }
2773
+ : {
2774
+ path: unit.path,
2775
+ kind: unit.kind,
2776
+ action: 'skipped',
2777
+ reason: ownership,
2778
+ };
2779
+ }
2780
+ return null;
2781
+ }
2782
+ async function pathKind(filePath) {
2783
+ try {
2784
+ const stat = await lstat(filePath);
2785
+ return stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
2786
+ }
2787
+ catch (error) {
2788
+ if (error.code === 'ENOENT') {
2789
+ return 'missing';
2790
+ }
2791
+ throw error;
2792
+ }
2793
+ }
2794
+ async function syncDirectoryUnit(unit, source, writer, force) {
2795
+ const localRoot = path.join(writer.projectRoot, unit.path);
2796
+ const replace = async () => {
2797
+ const files = [];
2798
+ for (const file of unit.files ?? []) {
2799
+ files.push([file, await readSourceFile(source, `${unit.path}/${file}`)]);
2800
+ }
2801
+ await writer.replaceDirectory(unit.path, files);
2802
+ };
2803
+ const kind = await pathKind(localRoot);
2804
+ const localFiles = kind === 'directory' ? await readTree(localRoot) : null;
2805
+ if (kind === 'missing' || localFiles?.size === 0) {
2806
+ await replace();
2807
+ return { path: unit.path, kind: unit.kind, action: 'created' };
2808
+ }
2809
+ if (localFiles == null) {
2810
+ // A file or link where the skill folder belongs.
2811
+ if (!force) {
2812
+ return {
2813
+ path: unit.path,
2814
+ kind: unit.kind,
2815
+ action: 'skipped',
2816
+ reason: 'unmanaged',
2817
+ };
2818
+ }
2819
+ await writer.remove(unit.path);
2820
+ await replace();
2821
+ return {
2822
+ path: unit.path,
2823
+ kind: unit.kind,
2824
+ action: 'updated',
2825
+ reason: 'forced',
2826
+ };
2827
+ }
2828
+ const skill = localFiles.get('SKILL.md');
2829
+ const ownership = classify(directoryUnitHash(localFiles), unit.sha256, typeof skill === 'string' ? readStamp(skill) : null, source.manifest.legacy[unit.path], source.manifest.version);
2830
+ if (ownership === 'unchanged') {
2831
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2832
+ }
2833
+ const result = replacementResult(unit, ownership, force);
2834
+ if (result.action === 'updated') {
2835
+ await replace();
2836
+ }
2837
+ return result;
2838
+ }
2839
+ async function syncFileUnit(unit, source, writer, force) {
2840
+ const local = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2841
+ const next = await readSourceFile(source, unit.path);
2842
+ if (local == null) {
2843
+ await writer.write(unit.path, next);
2844
+ return { path: unit.path, kind: unit.kind, action: 'created' };
2845
+ }
2846
+ const ownership = classify(fileUnitHash(local), unit.sha256, readStamp(local), source.manifest.legacy[unit.path], source.manifest.version);
2847
+ if (ownership === 'unchanged') {
2848
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2849
+ }
2850
+ const result = replacementResult(unit, ownership, force);
2851
+ if (result.action === 'updated') {
2852
+ await writer.write(unit.path, next);
2853
+ }
2854
+ return result;
2855
+ }
2856
+ async function syncBlockUnit(unit, source, writer, force) {
2857
+ const local = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2858
+ const block = (await readSourceFile(source, unit.path)).toString('utf8');
2859
+ if (local == null) {
2860
+ await writer.write(unit.path, block);
2861
+ return { path: unit.path, kind: unit.kind, action: 'created' };
2862
+ }
2863
+ const normalized = normalizeText(local);
2864
+ const begins = normalized.match(BLOCK_BEGIN)?.length ?? 0;
2865
+ const ends = normalized.match(BLOCK_END)?.length ?? 0;
2866
+ const match = normalized.match(BLOCK_PATTERN);
2867
+ if (begins > 0 || ends > 0) {
2868
+ if (begins !== 1 || ends !== 1 || !match) {
2869
+ // A lost END line or a duplicated block: neither appending nor
2870
+ // replacing can tell IWSDK's text from the developer's.
2871
+ return {
2872
+ path: unit.path,
2873
+ kind: unit.kind,
2874
+ action: 'skipped',
2875
+ reason: 'malformed-block',
2876
+ detail: 'Its iwsdk-agent-guidance markers are broken. Keep exactly one BEGIN and one END line, or delete the block, then sync again.',
2877
+ };
2878
+ }
2879
+ const ownership = classify(blockUnitHash(match[3]), unit.sha256, { version: match[1], sha256: match[2] }, undefined, source.manifest.version);
2880
+ if (ownership === 'unchanged') {
2881
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2882
+ }
2883
+ const result = replacementResult(unit, ownership, force);
2884
+ if (result.action === 'updated') {
2885
+ await writer.write(unit.path, withLineEndings(normalized.replace(BLOCK_PATTERN, () => block), local));
2886
+ }
2887
+ return result;
2888
+ }
2889
+ if (source.manifest.legacy[unit.path]?.includes(fileUnitHash(local))) {
2890
+ await writer.write(unit.path, withLineEndings(block, local));
2891
+ return {
2892
+ path: unit.path,
2893
+ kind: unit.kind,
2894
+ action: 'updated',
2895
+ reason: 'legacy',
2896
+ };
2897
+ }
2898
+ if (LEGACY_IWSDK_HEADING.test(normalized.trimStart())) {
2899
+ // An edited copy of guidance from a release before the managed block.
2900
+ // Appending would leave two contradicting versions in one file.
2901
+ if (!force) {
2902
+ return {
2903
+ path: unit.path,
2904
+ kind: unit.kind,
2905
+ action: 'skipped',
2906
+ reason: 'legacy-modified',
2907
+ detail: 'It holds edited guidance from an IWSDK release before 1.2; --force replaces the whole file.',
2908
+ };
2909
+ }
2910
+ await writer.write(unit.path, withLineEndings(block, local));
2911
+ return {
2912
+ path: unit.path,
2913
+ kind: unit.kind,
2914
+ action: 'updated',
2915
+ reason: 'forced',
2916
+ };
2917
+ }
2918
+ await writer.write(unit.path, withLineEndings(`${withTrailingNewline(normalized)}${normalized.trim() ? '\n' : ''}${block}`, local));
2919
+ return {
2920
+ path: unit.path,
2921
+ kind: unit.kind,
2922
+ action: 'updated',
2923
+ reason: 'appended',
2924
+ };
2925
+ }
2926
+ async function syncClaudeImport(unit, source, writer, force) {
2927
+ const rootFile = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2928
+ const nestedFile = await readTextIfExists(path.join(writer.projectRoot, '.claude', 'CLAUDE.md'));
2929
+ const next = await readSourceFile(source, unit.path);
2930
+ if (rootFile == null && nestedFile == null) {
2931
+ await writer.write(unit.path, next);
2932
+ return { path: unit.path, kind: unit.kind, action: 'created' };
2933
+ }
2934
+ if (rootFile != null &&
2935
+ (await isSameFile(path.join(writer.projectRoot, unit.path), path.join(writer.projectRoot, 'AGENTS.md')))) {
2936
+ // CLAUDE.md is a link to AGENTS.md: Claude already reads the guidance.
2937
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2938
+ }
2939
+ if (rootFile != null &&
2940
+ fileUnitHash(rootFile) !== fileUnitHash(next.toString('utf8')) &&
2941
+ source.manifest.legacy[unit.path]?.includes(fileUnitHash(rootFile))) {
2942
+ // Releases before 1.0 put the full guidance in CLAUDE.md.
2943
+ await writer.write(unit.path, withLineEndings(next.toString('utf8'), rootFile));
2944
+ return {
2945
+ path: unit.path,
2946
+ kind: unit.kind,
2947
+ action: 'updated',
2948
+ reason: 'legacy',
2949
+ };
2950
+ }
2951
+ if (rootFile != null &&
2952
+ !/^@AGENTS\.md\s*$/mu.test(rootFile) &&
2953
+ LEGACY_IWSDK_HEADING.test(normalizeText(rootFile).trimStart())) {
2954
+ if (!force) {
2955
+ return {
2956
+ path: unit.path,
2957
+ kind: unit.kind,
2958
+ action: 'skipped',
2959
+ reason: 'legacy-modified',
2960
+ detail: 'It holds edited guidance from an IWSDK release before 1.0; --force replaces the whole file with an @AGENTS.md import.',
2961
+ };
2962
+ }
2963
+ await writer.write(unit.path, withLineEndings(next.toString('utf8'), rootFile));
2964
+ return {
2965
+ path: unit.path,
2966
+ kind: unit.kind,
2967
+ action: 'updated',
2968
+ reason: 'forced',
2969
+ };
2970
+ }
2971
+ if ((rootFile != null && /^@AGENTS\.md\s*$/mu.test(rootFile)) ||
2972
+ (nestedFile != null && /^@\.\.\/AGENTS\.md\s*$/mu.test(nestedFile))) {
2973
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2974
+ }
2975
+ if (rootFile != null) {
2976
+ await writer.write(unit.path, withLineEndings(`${withTrailingNewline(rootFile)}\n@AGENTS.md\n`, rootFile));
2977
+ return {
2978
+ path: unit.path,
2979
+ kind: unit.kind,
2980
+ action: 'updated',
2981
+ reason: 'appended',
2982
+ };
2983
+ }
2984
+ await writer.write('.claude/CLAUDE.md', withLineEndings(`${withTrailingNewline(nestedFile)}\n@../AGENTS.md\n`, nestedFile));
2985
+ return {
2986
+ path: '.claude/CLAUDE.md',
2987
+ kind: unit.kind,
2988
+ action: 'updated',
2989
+ reason: 'appended',
2990
+ };
2991
+ }
2992
+ /** Skill names IWSDK has shipped: this release's and every earlier one's. */
2993
+ function ownedSkillNames(manifest) {
2994
+ const names = new Set();
2995
+ for (const unit of manifest.units) {
2996
+ for (const skill of unit.skills ?? []) {
2997
+ names.add(skill);
2998
+ }
2999
+ }
3000
+ for (const unitPath of Object.keys(manifest.legacy)) {
3001
+ const match = unitPath.match(/^\.(?:claude|agents)\/skills\/([^/]+)$/u);
3002
+ if (match) {
3003
+ names.add(match[1]);
3004
+ }
3005
+ }
3006
+ return names;
3007
+ }
3008
+ async function syncClaudeSettings$1(unit, source, writer, installedSkills, retiredSkills, force) {
3009
+ const filePath = path.join(writer.projectRoot, unit.path);
3010
+ const raw = await readTextIfExists(filePath);
3011
+ let settings = {};
3012
+ if (raw != null) {
3013
+ let parsed;
3014
+ try {
3015
+ parsed = JSON.parse(raw);
3016
+ }
3017
+ catch {
3018
+ parsed = undefined;
3019
+ }
3020
+ if (typeof parsed !== 'object' ||
3021
+ parsed === null ||
3022
+ Array.isArray(parsed)) {
3023
+ return {
3024
+ path: unit.path,
3025
+ kind: unit.kind,
3026
+ action: 'skipped',
3027
+ reason: 'invalid-json',
3028
+ detail: `${filePath} is not a JSON object (comments and trailing commas are not supported), so its IWSDK skill permissions were not updated.`,
3029
+ };
3030
+ }
3031
+ settings = parsed;
3032
+ }
3033
+ const permissions = typeof settings.permissions === 'object' &&
3034
+ settings.permissions !== null &&
3035
+ !Array.isArray(settings.permissions)
3036
+ ? { ...settings.permissions }
3037
+ : {};
3038
+ const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
3039
+ const shipped = new Set(unit.skills ?? []);
3040
+ const owned = new Set([
3041
+ ...ownedSkillNames(source.manifest),
3042
+ ...retiredSkills,
3043
+ ]);
3044
+ // Grant skills this sync installed (all of them for a new settings file);
3045
+ // a permission the developer removed for an untouched skill stays removed.
3046
+ // Grant every shipped skill when the file is new, when --force is given, or
3047
+ // when no IWSDK skill permission is left (after `adapter prune`, say).
3048
+ const grantAll = raw == null ||
3049
+ force ||
3050
+ !allow.some((rule) => {
3051
+ const name = typeof rule === 'string'
3052
+ ? rule.match(SKILL_PERMISSION)?.[1]
3053
+ : undefined;
3054
+ return name != null && owned.has(name);
3055
+ });
3056
+ const grant = [...shipped].filter((name) => grantAll || installedSkills.has(name));
3057
+ const isRetired = (rule) => {
3058
+ const name = typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
3059
+ return name != null && owned.has(name) && !shipped.has(name);
3060
+ };
3061
+ const nextAllow = allow.filter((rule) => !isRetired(rule));
3062
+ for (const name of grant) {
3063
+ if (!nextAllow.includes(`Skill(${name})`)) {
3064
+ nextAllow.push(`Skill(${name})`);
3065
+ }
3066
+ }
3067
+ if (raw != null &&
3068
+ nextAllow.length === allow.length &&
3069
+ nextAllow.every((rule, index) => rule === allow[index])) {
3070
+ return { path: unit.path, kind: unit.kind, action: 'unchanged' };
3071
+ }
3072
+ permissions.allow = nextAllow;
3073
+ const next = {
3074
+ $schema: 'https://json.schemastore.org/claude-code-settings.json',
3075
+ ...settings,
3076
+ permissions,
3077
+ };
3078
+ await writer.write(unit.path, `${JSON.stringify(next, null, 2)}\n`);
3079
+ return {
3080
+ path: unit.path,
3081
+ kind: unit.kind,
3082
+ action: raw == null ? 'created' : 'updated',
3083
+ };
3084
+ }
3085
+ /** Where retired units can be left behind, and the tools that use them. */
3086
+ const PRUNE_ROOTS = [
3087
+ {
3088
+ directory: '.claude/skills',
3089
+ kind: 'directory',
3090
+ match: /^iwsdk-/u,
3091
+ tools: ['claude'],
3092
+ },
3093
+ {
3094
+ directory: '.agents/skills',
3095
+ kind: 'directory',
3096
+ match: /^iwsdk-/u,
3097
+ tools: ['codex', 'cursor', 'copilot', 'opencode'],
3098
+ },
3099
+ {
3100
+ directory: '.claude/rules',
3101
+ kind: 'file',
3102
+ match: /\.md$/u,
3103
+ tools: ['claude'],
3104
+ },
3105
+ {
3106
+ directory: '.claude/agents',
3107
+ kind: 'file',
3108
+ match: /\.md$/u,
3109
+ tools: ['claude'],
3110
+ },
3111
+ {
3112
+ directory: '.cursor/rules',
3113
+ kind: 'file',
3114
+ match: /\.mdc$/u,
3115
+ tools: ['cursor'],
3116
+ },
3117
+ {
3118
+ directory: '.github/instructions',
3119
+ kind: 'file',
3120
+ match: /\.instructions\.md$/u,
3121
+ tools: ['copilot'],
3122
+ },
3123
+ ];
3124
+ function toolsForPath(unitPath) {
3125
+ const root = PRUNE_ROOTS.find((candidate) => unitPath.startsWith(`${candidate.directory}/`));
3126
+ if (root) {
3127
+ return root.tools;
3128
+ }
3129
+ if (unitPath.startsWith('.cursor/')) {
3130
+ return ['cursor'];
3131
+ }
3132
+ if (unitPath.startsWith('.github/')) {
3133
+ return ['copilot'];
3134
+ }
3135
+ return GUIDANCE_TOOLS;
3136
+ }
3137
+ async function pruneRetiredUnits(source, tools, writer) {
3138
+ const shipped = new Set(source.manifest.units.map((unit) => unit.path));
3139
+ const blocks = new Set(source.manifest.units
3140
+ .filter((unit) => unit.kind === 'block' || unit.kind === 'claude-import')
3141
+ .map((unit) => unit.path));
3142
+ const candidates = new Map();
3143
+ for (const root of PRUNE_ROOTS) {
3144
+ if (!root.tools.some((tool) => tools.includes(tool))) {
3145
+ continue;
3146
+ }
3147
+ let entries;
3148
+ try {
3149
+ entries = await readdir(path.join(writer.projectRoot, root.directory), {
3150
+ withFileTypes: true,
3151
+ });
3152
+ }
3153
+ catch {
3154
+ continue;
3155
+ }
3156
+ for (const entry of entries) {
3157
+ if (root.match.test(entry.name) &&
3158
+ (root.kind === 'directory' ? entry.isDirectory() : entry.isFile())) {
3159
+ candidates.set(`${root.directory}/${entry.name}`, root.kind);
3160
+ }
3161
+ }
3162
+ }
3163
+ // Files earlier releases wrote outside these folders, such as 0.4's
3164
+ // .github/copilot-instructions.md, are known by path from the legacy table.
3165
+ for (const unitPath of Object.keys(source.manifest.legacy)) {
3166
+ if (!candidates.has(unitPath) &&
3167
+ !blocks.has(unitPath) &&
3168
+ toolsForPath(unitPath).some((tool) => tools.includes(tool))) {
3169
+ const kind = await pathKind(path.join(writer.projectRoot, unitPath));
3170
+ if (kind === 'directory' || kind === 'file') {
3171
+ candidates.set(unitPath, kind);
3172
+ }
3173
+ }
3174
+ }
3175
+ const results = [];
3176
+ const removedSkills = new Set();
3177
+ for (const directory of ['.', ...PRUNE_ROOTS.map((root) => root.directory)]) {
3178
+ let entries;
3179
+ try {
3180
+ entries = await readdir(path.join(writer.projectRoot, directory));
3181
+ }
3182
+ catch {
3183
+ continue;
3184
+ }
3185
+ for (const name of entries.filter((entry) => TEMPORARY_SIBLING.test(entry) && !isInUse(entry))) {
3186
+ await writer.remove(path.posix.join(directory, name));
3187
+ }
3188
+ }
3189
+ for (const [unitPath, kind] of candidates) {
3190
+ if (shipped.has(unitPath)) {
3191
+ continue;
3192
+ }
3193
+ const name = path.posix.basename(unitPath);
3194
+ let localHash;
3195
+ let stamp;
3196
+ if (kind === 'directory') {
3197
+ const files = await readTree(path.join(writer.projectRoot, unitPath));
3198
+ const skill = files.get('SKILL.md');
3199
+ localHash = directoryUnitHash(files);
3200
+ stamp = typeof skill === 'string' ? readStamp(skill) : null;
3201
+ }
3202
+ else {
3203
+ const text = await readFile(path.join(writer.projectRoot, unitPath), 'utf8');
3204
+ localHash = fileUnitHash(text);
3205
+ stamp = readStamp(text);
3206
+ }
3207
+ if (stamp?.name != null && stamp.name !== name) {
3208
+ // A copy of an IWSDK unit the developer saved under another name.
3209
+ continue;
3210
+ }
3211
+ const ownership = classify(localHash, undefined, stamp, source.manifest.legacy[unitPath], source.manifest.version);
3212
+ if (ownership === 'managed' || ownership === 'legacy') {
3213
+ await writer.remove(unitPath);
3214
+ results.push({ path: unitPath, kind, action: 'removed' });
3215
+ if (kind === 'directory') {
3216
+ removedSkills.add(name);
3217
+ }
3218
+ }
3219
+ else if (ownership === 'modified') {
3220
+ // A retired IWSDK unit the developer edited: keep it, but say so.
3221
+ results.push({
3222
+ path: unitPath,
3223
+ kind,
3224
+ action: 'skipped',
3225
+ reason: 'modified',
3226
+ });
3227
+ }
3228
+ }
3229
+ return { results, removedSkills };
3230
+ }
3231
+ function readSkillDescription(text) {
3232
+ const frontmatter = normalizeText(text).match(/^---\n([\s\S]*?)\n---/u)?.[1];
3233
+ if (!frontmatter) {
3234
+ return '';
3235
+ }
3236
+ const lines = frontmatter.split('\n');
3237
+ const index = lines.findIndex((line) => line.startsWith('description:'));
3238
+ if (index === -1) {
3239
+ return '';
3240
+ }
3241
+ const inline = lines[index].slice('description:'.length).trim();
3242
+ if (inline && !/^[>|]-?$/u.test(inline)) {
3243
+ return inline.replace(/^['"]|['"]$/gu, '');
3244
+ }
3245
+ const folded = [];
3246
+ for (const line of lines.slice(index + 1)) {
3247
+ if (!/^\s+\S/u.test(line)) {
3248
+ break;
3249
+ }
3250
+ folded.push(line.trim());
3251
+ }
3252
+ return folded.join(' ');
3253
+ }
3254
+ async function summarizeSkills(source, tools) {
3255
+ const byName = new Map();
3256
+ for (const unit of selectedUnits(source.manifest, tools)) {
3257
+ if (unit.kind !== 'directory') {
3258
+ continue;
3259
+ }
3260
+ const name = unit.path.split('/').pop();
3261
+ const summary = byName.get(name) ?? {
3262
+ name,
3263
+ description: readSkillDescription((await readSourceFile(source, `${unit.path}/SKILL.md`)).toString('utf8')),
3264
+ paths: [],
3265
+ };
3266
+ summary.paths.push(`${unit.path}/SKILL.md`);
3267
+ byName.set(name, summary);
3268
+ }
3269
+ for (const summary of byName.values()) {
3270
+ // Claude Code's copy first; it is the path most sessions can load.
3271
+ summary.paths.sort((left, right) => left.startsWith('.claude/') === right.startsWith('.claude/')
3272
+ ? left.localeCompare(right)
3273
+ : left.startsWith('.claude/')
3274
+ ? -1
3275
+ : 1);
3276
+ }
3277
+ return [...byName.values()].sort((left, right) => left.name === 'iwsdk-dev'
3278
+ ? -1
3279
+ : right.name === 'iwsdk-dev'
3280
+ ? 1
3281
+ : left.name.localeCompare(right.name));
3282
+ }
3283
+ function buildAgentNotice(source, skills, dryRun, changedCount) {
3284
+ const version = source.manifest.version;
3285
+ const entry = skills.find((skill) => skill.name === 'iwsdk-dev');
3286
+ return [
3287
+ dryRun
3288
+ ? `This project is checked against IWSDK ${version} agent guidance.`
3289
+ : changedCount > 0
3290
+ ? `Installed IWSDK ${version} agent guidance in this project (${changedCount} file${changedCount === 1 ? '' : 's'} or folder${changedCount === 1 ? '' : 's'} written or removed).`
3291
+ : `This project's IWSDK ${version} agent guidance is already current; nothing was written.`,
3292
+ ...(source.origin === 'bundled-cli'
3293
+ ? [
3294
+ `This project does not list @iwsdk/core yet, so this is the guidance bundled with @iwsdk/cli (IWSDK ${version}). Run this command again after installing IWSDK.`,
3295
+ ]
3296
+ : []),
3297
+ RETIRED_SURFACES_NOTICE,
3298
+ entry
3299
+ ? `Before writing IWSDK code, read the iwsdk-agent-guidance block in AGENTS.md, then ${entry.paths.join(' or ')}.`
3300
+ : 'Before writing IWSDK code, read the iwsdk-agent-guidance block in AGENTS.md.',
3301
+ 'Skills installed mid-session may not be listed until the next session; read their SKILL.md files directly when the task matches:',
3302
+ ...skills.map((skill) => `- ${skill.name} (${skill.paths[0]}): ${skill.description.length > 220 ? `${skill.description.slice(0, 217)}...` : skill.description}`),
3303
+ ].join('\n');
3304
+ }
3305
+ /**
3306
+ * Write a guidance release into a project. Files IWSDK wrote and nobody edited
3307
+ * are replaced; edited files and files IWSDK does not own are reported and left
3308
+ * alone unless `force` is set; retired IWSDK files are removed.
3309
+ */
3310
+ async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, }) {
3311
+ const writer = createWriter(projectRoot, dryRun);
3312
+ const pruned = await pruneRetiredUnits(source, tools, writer);
3313
+ const results = [];
3314
+ const installedSkills = new Set();
3315
+ const units = selectedUnits(source.manifest, tools);
3316
+ // Settings last: they grant the skills this run installed.
3317
+ for (const unit of [
3318
+ ...units.filter((candidate) => candidate.kind !== 'claude-settings'),
3319
+ ...units.filter((candidate) => candidate.kind === 'claude-settings'),
3320
+ ]) {
3321
+ switch (unit.kind) {
3322
+ case 'directory': {
3323
+ const result = await syncDirectoryUnit(unit, source, writer, force);
3324
+ if (unit.path.startsWith('.claude/') &&
3325
+ (result.action === 'created' || result.action === 'updated')) {
3326
+ installedSkills.add(path.posix.basename(unit.path));
3327
+ }
3328
+ results.push(result);
3329
+ break;
3330
+ }
3331
+ case 'file':
3332
+ results.push(await syncFileUnit(unit, source, writer, force));
3333
+ break;
3334
+ case 'block':
3335
+ results.push(await syncBlockUnit(unit, source, writer, force));
3336
+ break;
3337
+ case 'claude-import':
3338
+ results.push(await syncClaudeImport(unit, source, writer, force));
3339
+ break;
3340
+ case 'claude-settings':
3341
+ results.push(await syncClaudeSettings$1(unit, source, writer, installedSkills, pruned.removedSkills, force));
3342
+ break;
3343
+ }
3344
+ }
3345
+ results.push(...pruned.results);
3346
+ const skills = await summarizeSkills(source, tools);
3347
+ const changedCount = results.filter((result) => result.action !== 'unchanged' && result.action !== 'skipped').length;
3348
+ return {
3349
+ projectRoot,
3350
+ version: source.manifest.version,
3351
+ origin: source.origin,
3352
+ tools: [...tools],
3353
+ dryRun,
3354
+ changed: changedCount > 0,
3355
+ results,
3356
+ skipped: results.filter((result) => result.action === 'skipped'),
3357
+ skills,
3358
+ agentNotice: buildAgentNotice(source, skills, dryRun, changedCount),
3359
+ };
3360
+ }
3361
+ /**
3362
+ * The project that receives guidance: the nearest directory at or above
3363
+ * `startDirectory` with a package.json. In a monorepo, run from the app's
3364
+ * directory or pass --workspace.
2377
3365
  */
2378
- function getUnsupportedNodeMessage(version, requiredRange) {
2379
- if (semver$1.satisfies(version, requiredRange, { includePrerelease: true })) {
2380
- return undefined;
3366
+ function findGuidanceProjectRoot(startDirectory) {
3367
+ let current = path.resolve(startDirectory);
3368
+ while (true) {
3369
+ if (existsSync(path.join(current, 'package.json'))) {
3370
+ return current;
3371
+ }
3372
+ const parent = path.dirname(current);
3373
+ if (parent === current) {
3374
+ return null;
3375
+ }
3376
+ current = parent;
2381
3377
  }
2382
- return (`Unsupported Node.js version: ${version}. IWSDK requires Node ${requiredRange}. ` +
2383
- 'Upgrade Node (for example with nvm or Volta) and retry.');
2384
3378
  }
2385
-
2386
- const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
2387
- const CLI_VERSION = "1.1.0-rc.2";
3379
+ /**
3380
+ * The coding tools a project already has IWSDK guidance for, judged from
3381
+ * files only those tools read. Codex and OpenCode read the same files
3382
+ * (`.agents/skills` and nested `AGENTS.md`), so they count together.
3383
+ */
3384
+ async function installedGuidanceTools(projectRoot, source) {
3385
+ const present = new Set();
3386
+ // Units several tools share (`.agents/skills`) are left for last: they
3387
+ // mean Codex/OpenCode only when no tool that shares them has its own files.
3388
+ const shared = [];
3389
+ const add = (tools) => {
3390
+ if (tools.length === 1) {
3391
+ present.add(tools[0]);
3392
+ }
3393
+ else {
3394
+ shared.push(tools);
3395
+ }
3396
+ };
3397
+ for (const unit of source.manifest.units) {
3398
+ // Settings and CLAUDE.md are written by MCP setup and by developers too.
3399
+ if (unit.tools.length < GUIDANCE_TOOLS.length &&
3400
+ (unit.kind === 'directory' ||
3401
+ unit.kind === 'file' ||
3402
+ (unit.kind === 'block' &&
3403
+ // A nested AGENTS.md counts only when it holds IWSDK's block.
3404
+ (await readTextIfExists(path.join(projectRoot, unit.path)))?.match(BLOCK_BEGIN) != null)) &&
3405
+ existsSync(path.join(projectRoot, unit.path))) {
3406
+ add(unit.tools);
3407
+ }
3408
+ }
3409
+ // A file from an earlier release counts only when it is that release's file.
3410
+ for (const [unitPath, hashes] of Object.entries(source.manifest.legacy)) {
3411
+ const tools = toolsForPath(unitPath);
3412
+ const filePath = path.join(projectRoot, unitPath);
3413
+ if (tools.length === GUIDANCE_TOOLS.length || !existsSync(filePath)) {
3414
+ continue;
3415
+ }
3416
+ const hash = (await pathKind(filePath)) === 'directory'
3417
+ ? directoryUnitHash(await readTree(filePath))
3418
+ : fileUnitHash(await readFile(filePath, 'utf8'));
3419
+ if (hashes.includes(hash)) {
3420
+ add(tools);
3421
+ }
3422
+ }
3423
+ for (const tools of shared) {
3424
+ if (tools.includes('codex') &&
3425
+ !tools.some((tool) => tool !== 'codex' && tool !== 'opencode' && present.has(tool))) {
3426
+ present.add('codex');
3427
+ present.add('opencode');
3428
+ }
3429
+ }
3430
+ return GUIDANCE_TOOLS.filter((tool) => present.has(tool));
3431
+ }
2388
3432
 
2389
3433
  /**
2390
3434
  * Copyright (c) Meta Platforms, Inc. and affiliates.
@@ -2454,7 +3498,7 @@ function parseOptionalPositiveIntegerOption(value, label) {
2454
3498
  * This source code is licensed under the MIT license found in the
2455
3499
  * LICENSE file in the root directory of this source tree.
2456
3500
  */
2457
- function isRecord$7(value) {
3501
+ function isRecord$8(value) {
2458
3502
  return typeof value === 'object' && value !== null && !Array.isArray(value);
2459
3503
  }
2460
3504
  function createSuccess(data) {
@@ -2483,10 +3527,10 @@ function writeJson(stream, value) {
2483
3527
  stream.write(`${JSON.stringify(value, null, 2)}\n`);
2484
3528
  }
2485
3529
  function isCliRawOutput(value) {
2486
- return isRecord$7(value) && value.__raw === true;
3530
+ return isRecord$8(value) && value.__raw === true;
2487
3531
  }
2488
3532
  function isCliFailure(value) {
2489
- return isRecord$7(value) && value.ok === false && isRecord$7(value.error);
3533
+ return isRecord$8(value) && value.ok === false && isRecord$8(value.error);
2490
3534
  }
2491
3535
 
2492
3536
  var runtimeServerName = "iwsdk-runtime";
@@ -2537,6 +3581,7 @@ const TIMED_RUNTIME_METHODS = new Set([
2537
3581
  'set_select_value',
2538
3582
  ]);
2539
3583
  const BROWSER_RUNTIME_METHODS = new Set([
3584
+ 'browser_filmstrip',
2540
3585
  'browser_interact',
2541
3586
  'browser_profile',
2542
3587
  'browser_set_muted',
@@ -2591,7 +3636,7 @@ function closestShapeError(value, candidates, errors) {
2591
3636
  if (sameKind.length === 1) {
2592
3637
  return sameKind[0].error;
2593
3638
  }
2594
- if (!isRecord$6(value)) {
3639
+ if (!isRecord$7(value)) {
2595
3640
  return null;
2596
3641
  }
2597
3642
  const keys = Object.keys(value);
@@ -2658,7 +3703,7 @@ function assertSchemaValue(value, schema, path) {
2658
3703
  const typeMatches = schema.type == null ||
2659
3704
  (schema.type === 'null' && value === null) ||
2660
3705
  (schema.type === 'array' && Array.isArray(value)) ||
2661
- (schema.type === 'object' && isRecord$6(value)) ||
3706
+ (schema.type === 'object' && isRecord$7(value)) ||
2662
3707
  (schema.type === 'integer' && Number.isInteger(value)) ||
2663
3708
  (schema.type === 'number' &&
2664
3709
  typeof value === 'number' &&
@@ -2701,7 +3746,7 @@ function assertSchemaValue(value, schema, path) {
2701
3746
  value.forEach((entry, index) => assertSchemaValue(entry, schema.items, `${path}[${index}]`));
2702
3747
  }
2703
3748
  }
2704
- if (isRecord$6(value)) {
3749
+ if (isRecord$7(value)) {
2705
3750
  const properties = schema.properties;
2706
3751
  for (const required of schema.required ?? []) {
2707
3752
  if (!Object.prototype.hasOwnProperty.call(value, required)) {
@@ -3817,6 +4862,34 @@ const ALL_RUNTIME_MCP_TOOLS = [
3817
4862
  additionalProperties: false,
3818
4863
  },
3819
4864
  },
4865
+ {
4866
+ name: 'browser_filmstrip',
4867
+ description: 'Capture a frame-accurate sequence of the application: pause the ECS, capture the current frame, then step `every` simulation frames and capture again until `count` frames are taken, and return one contact-sheet image (screenshotPath) with each panel labeled by its frame offset. Restores the previous pause state. Use it to see motion (physics, animation, locomotion) independently of how fast the browser renders.',
4868
+ inputSchema: {
4869
+ type: 'object',
4870
+ properties: {
4871
+ count: {
4872
+ type: 'integer',
4873
+ minimum: 2,
4874
+ maximum: 12,
4875
+ description: 'Frames to capture, including the current one. Defaults to 6.',
4876
+ },
4877
+ every: {
4878
+ type: 'integer',
4879
+ minimum: 1,
4880
+ maximum: 120,
4881
+ description: 'Simulation frames to step between captures (fixed 1/72 s timestep). Defaults to 5.',
4882
+ },
4883
+ format: {
4884
+ type: 'string',
4885
+ enum: ['png', 'jpeg'],
4886
+ description: 'Image format of the contact sheet. Defaults to png.',
4887
+ },
4888
+ },
4889
+ required: [],
4890
+ additionalProperties: false,
4891
+ },
4892
+ },
3820
4893
  {
3821
4894
  name: 'browser_snapshot',
3822
4895
  description: 'Inspect the current application as a compact accessibility-first list of interactive elements and canvas regions. Use returned refs with browser_interact.',
@@ -5841,6 +6914,7 @@ const RUNTIME_TOOL_TO_METHOD = {
5841
6914
  xr_cancel_sequence: 'cancel_sequence',
5842
6915
  xr_list_targets: 'list_targets',
5843
6916
  browser_screenshot: 'screenshot',
6917
+ browser_filmstrip: 'browser_filmstrip',
5844
6918
  browser_snapshot: 'browser_snapshot',
5845
6919
  browser_interact: 'browser_interact',
5846
6920
  browser_profile: 'browser_profile',
@@ -5866,6 +6940,7 @@ const ALL_RUNTIME_CLI_PATHS = {
5866
6940
  xr_get_gamepad_state: ['xr', 'get-gamepad-state'],
5867
6941
  xr_set_gamepad_state: ['xr', 'set-gamepad-state'],
5868
6942
  browser_screenshot: ['browser', 'screenshot'],
6943
+ browser_filmstrip: ['browser', 'filmstrip'],
5869
6944
  browser_snapshot: ['browser', 'snapshot'],
5870
6945
  browser_interact: ['browser', 'interact'],
5871
6946
  browser_profile: ['browser', 'profile'],
@@ -5979,6 +7054,7 @@ const EDITOR_TARGET_MCP_TOOL_NAME_SET = new Set([
5979
7054
  ]);
5980
7055
  const HOST_BROWSER_MCP_TOOL_NAME_SET = new Set([
5981
7056
  'browser_screenshot',
7057
+ 'browser_filmstrip',
5982
7058
  'browser_snapshot',
5983
7059
  'browser_interact',
5984
7060
  'browser_profile',
@@ -6030,7 +7106,7 @@ function getRuntimeOperationByCliPath(domain, action) {
6030
7106
  function resolveRuntimeOperationRequest(operation, params) {
6031
7107
  const required = operation.inputSchema.required ?? [];
6032
7108
  if (required.length > 0) {
6033
- if (!isRecord$6(params)) {
7109
+ if (!isRecord$7(params)) {
6034
7110
  throw new Error(`${operation.mcpName} requires an object with parameter${required.length === 1 ? '' : 's'}: ${required.join(', ')}`);
6035
7111
  }
6036
7112
  const missing = required.filter((name) => !Object.prototype.hasOwnProperty.call(params, name));
@@ -6038,10 +7114,10 @@ function resolveRuntimeOperationRequest(operation, params) {
6038
7114
  throw new Error(`${operation.mcpName} requires parameter${missing.length === 1 ? '' : 's'}: ${missing.join(', ')}`);
6039
7115
  }
6040
7116
  }
6041
- const paramsRecord = isRecord$6(params) ? params : null;
7117
+ const paramsRecord = isRecord$7(params) ? params : null;
6042
7118
  const expectedTab = paramsRecord?.expectedTab;
6043
7119
  if (expectedTab !== undefined &&
6044
- (!isRecord$6(expectedTab) ||
7120
+ (!isRecord$7(expectedTab) ||
6045
7121
  typeof expectedTab.id !== 'string' ||
6046
7122
  !Number.isInteger(expectedTab.generation) ||
6047
7123
  expectedTab.generation < 1)) {
@@ -6059,13 +7135,13 @@ function resolveRuntimeOperationRequest(operation, params) {
6059
7135
  throw new Error('Physical runtimeTarget requires headsetId, pageId and tabGeneration from runtime_list_targets.');
6060
7136
  }
6061
7137
  if (selection &&
6062
- isRecord$6(expectedTab) &&
7138
+ isRecord$7(expectedTab) &&
6063
7139
  ((selection.pageId != null && selection.pageId !== expectedTab.id) ||
6064
7140
  (selection.tabGeneration != null &&
6065
7141
  selection.tabGeneration !== expectedTab.generation))) {
6066
7142
  throw new Error('runtimeTarget and expectedTab must identify the same page generation.');
6067
7143
  }
6068
- const target = isRecord$6(expectedTab) &&
7144
+ const target = isRecord$7(expectedTab) &&
6069
7145
  typeof expectedTab.id === 'string' &&
6070
7146
  typeof expectedTab.generation === 'number'
6071
7147
  ? {
@@ -6079,7 +7155,7 @@ function resolveRuntimeOperationRequest(operation, params) {
6079
7155
  : operation.target;
6080
7156
  return { params: commandParams, target };
6081
7157
  }
6082
- function isRecord$6(value) {
7158
+ function isRecord$7(value) {
6083
7159
  return typeof value === 'object' && value !== null && !Array.isArray(value);
6084
7160
  }
6085
7161
 
@@ -6853,7 +7929,7 @@ const ALL_MANAGED_MCP_SERVER_NAMES = [
6853
7929
  ];
6854
7930
  const TOML_BLOCK_START = '# --- IWER managed (do not edit) ---';
6855
7931
  const TOML_BLOCK_END = '# --- end IWER managed ---';
6856
- function isRecord$5(value) {
7932
+ function isRecord$6(value) {
6857
7933
  return typeof value === 'object' && value !== null && !Array.isArray(value);
6858
7934
  }
6859
7935
  function isNodeErrorWithCode$1(error, code) {
@@ -6913,7 +7989,7 @@ async function mergeJsonConfig(filePath, serverEntries, jsonKey, managedKeys) {
6913
7989
  try {
6914
7990
  const raw = await readFile(filePath, 'utf-8');
6915
7991
  const parsed = JSON.parse(raw);
6916
- if (!isRecord$5(parsed)) {
7992
+ if (!isRecord$6(parsed)) {
6917
7993
  throw new Error(`Existing JSON config at ${filePath} must contain a top-level object`);
6918
7994
  }
6919
7995
  existing = parsed;
@@ -6928,10 +8004,10 @@ async function mergeJsonConfig(filePath, serverEntries, jsonKey, managedKeys) {
6928
8004
  created = true;
6929
8005
  }
6930
8006
  const sectionValue = existing[jsonKey];
6931
- if (sectionValue != null && !isRecord$5(sectionValue)) {
8007
+ if (sectionValue != null && !isRecord$6(sectionValue)) {
6932
8008
  throw new Error(`Existing JSON config section "${jsonKey}" at ${filePath} must be an object`);
6933
8009
  }
6934
- const section = isRecord$5(sectionValue) ? { ...sectionValue } : {};
8010
+ const section = isRecord$6(sectionValue) ? { ...sectionValue } : {};
6935
8011
  if (managedKeys) {
6936
8012
  for (const key of managedKeys) {
6937
8013
  if (!(key in serverEntries)) {
@@ -6956,7 +8032,7 @@ async function unmergeJsonConfig(filePath, serverKeys, jsonKey, weCreatedFile) {
6956
8032
  let existing;
6957
8033
  try {
6958
8034
  const parsed = JSON.parse(raw);
6959
- if (!isRecord$5(parsed)) {
8035
+ if (!isRecord$6(parsed)) {
6960
8036
  return;
6961
8037
  }
6962
8038
  existing = parsed;
@@ -6965,7 +8041,7 @@ async function unmergeJsonConfig(filePath, serverKeys, jsonKey, weCreatedFile) {
6965
8041
  return;
6966
8042
  }
6967
8043
  const sectionValue = existing[jsonKey];
6968
- if (isRecord$5(sectionValue)) {
8044
+ if (isRecord$6(sectionValue)) {
6969
8045
  for (const key of serverKeys) {
6970
8046
  delete sectionValue[key];
6971
8047
  }
@@ -7056,7 +8132,7 @@ async function mergeOpenCodeConfig(filePath, serverEntries, managedKeys) {
7056
8132
  let created = false;
7057
8133
  try {
7058
8134
  const parsed = JSON.parse(await readFile(filePath, 'utf8'));
7059
- if (!isRecord$5(parsed)) {
8135
+ if (!isRecord$6(parsed)) {
7060
8136
  throw new Error(`Existing OpenCode config at ${filePath} must contain a top-level object`);
7061
8137
  }
7062
8138
  existing = parsed;
@@ -7071,10 +8147,10 @@ async function mergeOpenCodeConfig(filePath, serverEntries, managedKeys) {
7071
8147
  created = true;
7072
8148
  }
7073
8149
  const mcpValue = existing.mcp;
7074
- if (mcpValue != null && !isRecord$5(mcpValue)) {
8150
+ if (mcpValue != null && !isRecord$6(mcpValue)) {
7075
8151
  throw new Error(`Existing OpenCode config section "mcp" at ${filePath} must be an object`);
7076
8152
  }
7077
- const mcp = isRecord$5(mcpValue) ? { ...mcpValue } : {};
8153
+ const mcp = isRecord$6(mcpValue) ? { ...mcpValue } : {};
7078
8154
  for (const key of managedKeys) {
7079
8155
  delete mcp[key];
7080
8156
  }
@@ -7083,12 +8159,12 @@ async function mergeOpenCodeConfig(filePath, serverEntries, managedKeys) {
7083
8159
  const permissionValue = existing.permission;
7084
8160
  if (permissionValue != null &&
7085
8161
  typeof permissionValue !== 'string' &&
7086
- !isRecord$5(permissionValue)) {
8162
+ !isRecord$6(permissionValue)) {
7087
8163
  throw new Error(`Existing OpenCode config section "permission" at ${filePath} must be a string or object`);
7088
8164
  }
7089
8165
  const permission = typeof permissionValue === 'string'
7090
8166
  ? { '*': permissionValue }
7091
- : isRecord$5(permissionValue)
8167
+ : isRecord$6(permissionValue)
7092
8168
  ? { ...permissionValue }
7093
8169
  : {};
7094
8170
  for (const key of managedKeys) {
@@ -7107,7 +8183,7 @@ async function unmergeOpenCodeConfig(filePath, managedKeys, weCreatedFile) {
7107
8183
  let existing;
7108
8184
  try {
7109
8185
  const parsed = JSON.parse(await readFile(filePath, 'utf8'));
7110
- if (!isRecord$5(parsed)) {
8186
+ if (!isRecord$6(parsed)) {
7111
8187
  return;
7112
8188
  }
7113
8189
  existing = parsed;
@@ -7115,7 +8191,7 @@ async function unmergeOpenCodeConfig(filePath, managedKeys, weCreatedFile) {
7115
8191
  catch {
7116
8192
  return;
7117
8193
  }
7118
- if (isRecord$5(existing.mcp)) {
8194
+ if (isRecord$6(existing.mcp)) {
7119
8195
  for (const key of managedKeys) {
7120
8196
  delete existing.mcp[key];
7121
8197
  }
@@ -7123,7 +8199,7 @@ async function unmergeOpenCodeConfig(filePath, managedKeys, weCreatedFile) {
7123
8199
  delete existing.mcp;
7124
8200
  }
7125
8201
  }
7126
- if (isRecord$5(existing.permission)) {
8202
+ if (isRecord$6(existing.permission)) {
7127
8203
  for (const key of managedKeys) {
7128
8204
  delete existing.permission[openCodePermissionKey(key)];
7129
8205
  }
@@ -7240,7 +8316,7 @@ const CURSOR_PERMISSIONS_FILE = '.cursor/permissions.json';
7240
8316
  const OPENCODE_CONFIG_FILE = 'opencode.json';
7241
8317
  const OPENCODE_SKILL_PERMISSION = 'iwsdk-*';
7242
8318
  const CURSOR_ALLOW_PREFIX = 'Allow IWSDK-managed MCP tools from ';
7243
- function isRecord$4(value) {
8319
+ function isRecord$5(value) {
7244
8320
  return typeof value === 'object' && value !== null && !Array.isArray(value);
7245
8321
  }
7246
8322
  function isNodeErrorWithCode(error, code) {
@@ -7252,7 +8328,7 @@ function isNodeErrorWithCode(error, code) {
7252
8328
  async function readJsonObject(filePath) {
7253
8329
  try {
7254
8330
  const parsed = JSON.parse(await readFile(filePath, 'utf8'));
7255
- if (!isRecord$4(parsed)) {
8331
+ if (!isRecord$5(parsed)) {
7256
8332
  throw new Error(`Existing config at ${filePath} must contain an object`);
7257
8333
  }
7258
8334
  return { created: false, value: parsed };
@@ -7282,10 +8358,10 @@ async function syncClaudeSettings(workspaceRoot, serverNames) {
7282
8358
  const filePath = path.join(workspaceRoot, CLAUDE_SETTINGS_FILE);
7283
8359
  const { value } = await readJsonObject(filePath);
7284
8360
  const permissionsValue = value.permissions;
7285
- if (permissionsValue != null && !isRecord$4(permissionsValue)) {
8361
+ if (permissionsValue != null && !isRecord$5(permissionsValue)) {
7286
8362
  throw new Error(`Existing Claude settings section "permissions" at ${filePath} must be an object`);
7287
8363
  }
7288
- const permissions = isRecord$4(permissionsValue) ? { ...permissionsValue } : {};
8364
+ const permissions = isRecord$5(permissionsValue) ? { ...permissionsValue } : {};
7289
8365
  const allowValue = permissions.allow;
7290
8366
  if (allowValue != null && !Array.isArray(allowValue)) {
7291
8367
  throw new Error(`Existing Claude settings section "permissions.allow" at ${filePath} must be an array`);
@@ -7316,6 +8392,15 @@ async function syncClaudeSettings(workspaceRoot, serverNames) {
7316
8392
  value.$schema ??= 'https://json.schemastore.org/claude-code-settings.json';
7317
8393
  await writeJsonObject(filePath, value);
7318
8394
  }
8395
+ /** Skills IWSDK has shipped, so prune leaves a developer's own alone. */
8396
+ async function readOwnedSkillNames(workspaceRoot) {
8397
+ try {
8398
+ return ownedSkillNames((await resolveProjectGuidance(workspaceRoot)).manifest);
8399
+ }
8400
+ catch {
8401
+ return new Set();
8402
+ }
8403
+ }
7319
8404
  async function pruneClaudeSettings(workspaceRoot) {
7320
8405
  const filePath = path.join(workspaceRoot, CLAUDE_SETTINGS_FILE);
7321
8406
  if (!existsSync(filePath)) {
@@ -7323,8 +8408,15 @@ async function pruneClaudeSettings(workspaceRoot) {
7323
8408
  }
7324
8409
  const { value } = await readJsonObject(filePath);
7325
8410
  const permissions = value.permissions;
7326
- if (isRecord$4(permissions) && Array.isArray(permissions.allow)) {
7327
- const filteredAllow = permissions.allow.filter((rule) => !isManagedClaudePermission(rule));
8411
+ if (isRecord$5(permissions) && Array.isArray(permissions.allow)) {
8412
+ const ownedSkills = await readOwnedSkillNames(workspaceRoot);
8413
+ const filteredAllow = permissions.allow.filter((rule) => {
8414
+ const skill = typeof rule === 'string'
8415
+ ? rule.match(/^Skill\((iwsdk-[^)]*)\)$/u)?.[1]
8416
+ : undefined;
8417
+ return (!isManagedClaudePermission(rule) &&
8418
+ !(skill != null && ownedSkills.has(skill)));
8419
+ });
7328
8420
  if (filteredAllow.length === 0) {
7329
8421
  delete permissions.allow;
7330
8422
  }
@@ -7355,10 +8447,10 @@ async function syncCursorPermissions(workspaceRoot, serverNames) {
7355
8447
  const filePath = path.join(workspaceRoot, CURSOR_PERMISSIONS_FILE);
7356
8448
  const { value } = await readJsonObject(filePath);
7357
8449
  const autoRunValue = value.autoRun;
7358
- if (autoRunValue != null && !isRecord$4(autoRunValue)) {
8450
+ if (autoRunValue != null && !isRecord$5(autoRunValue)) {
7359
8451
  throw new Error(`Existing Cursor permissions section "autoRun" at ${filePath} must be an object`);
7360
8452
  }
7361
- const autoRun = isRecord$4(autoRunValue) ? { ...autoRunValue } : {};
8453
+ const autoRun = isRecord$5(autoRunValue) ? { ...autoRunValue } : {};
7362
8454
  const allowValue = autoRun.allow_instructions;
7363
8455
  if (allowValue != null && !Array.isArray(allowValue)) {
7364
8456
  throw new Error(`Existing Cursor permissions section "autoRun.allow_instructions" at ${filePath} must be an array`);
@@ -7380,7 +8472,7 @@ async function pruneCursorPermissions(workspaceRoot) {
7380
8472
  }
7381
8473
  const { value } = await readJsonObject(filePath);
7382
8474
  const autoRun = value.autoRun;
7383
- if (isRecord$4(autoRun) && Array.isArray(autoRun.allow_instructions)) {
8475
+ if (isRecord$5(autoRun) && Array.isArray(autoRun.allow_instructions)) {
7384
8476
  const filteredAllowInstructions = autoRun.allow_instructions.filter((entry) => typeof entry !== 'string' || !entry.startsWith(CURSOR_ALLOW_PREFIX));
7385
8477
  if (filteredAllowInstructions.length === 0) {
7386
8478
  delete autoRun.allow_instructions;
@@ -7400,23 +8492,23 @@ async function syncOpenCodeSkillPermissions(workspaceRoot) {
7400
8492
  const permissionValue = value.permission;
7401
8493
  if (permissionValue != null &&
7402
8494
  typeof permissionValue !== 'string' &&
7403
- !isRecord$4(permissionValue)) {
8495
+ !isRecord$5(permissionValue)) {
7404
8496
  throw new Error(`Existing OpenCode setting "permission" at ${filePath} must be a string or object`);
7405
8497
  }
7406
8498
  const permissions = typeof permissionValue === 'string'
7407
8499
  ? { '*': permissionValue }
7408
- : isRecord$4(permissionValue)
8500
+ : isRecord$5(permissionValue)
7409
8501
  ? { ...permissionValue }
7410
8502
  : {};
7411
8503
  const skillValue = permissions.skill;
7412
8504
  if (skillValue != null &&
7413
8505
  typeof skillValue !== 'string' &&
7414
- !isRecord$4(skillValue)) {
8506
+ !isRecord$5(skillValue)) {
7415
8507
  throw new Error(`Existing OpenCode setting "permission.skill" at ${filePath} must be a string or object`);
7416
8508
  }
7417
8509
  const skillPermissions = typeof skillValue === 'string'
7418
8510
  ? { '*': skillValue }
7419
- : isRecord$4(skillValue)
8511
+ : isRecord$5(skillValue)
7420
8512
  ? { ...skillValue }
7421
8513
  : {};
7422
8514
  skillPermissions[OPENCODE_SKILL_PERMISSION] = 'allow';
@@ -7431,7 +8523,7 @@ async function pruneOpenCodeSkillPermissions(workspaceRoot) {
7431
8523
  return;
7432
8524
  }
7433
8525
  const { value } = await readJsonObject(filePath);
7434
- if (isRecord$4(value.permission) && isRecord$4(value.permission.skill)) {
8526
+ if (isRecord$5(value.permission) && isRecord$5(value.permission.skill)) {
7435
8527
  delete value.permission.skill[OPENCODE_SKILL_PERMISSION];
7436
8528
  if (Object.keys(value.permission.skill).length === 0) {
7437
8529
  delete value.permission.skill;
@@ -7442,36 +8534,57 @@ async function pruneOpenCodeSkillPermissions(workspaceRoot) {
7442
8534
  }
7443
8535
  await writeJsonObject(filePath, value);
7444
8536
  }
7445
- function bundledAgentsPath() {
7446
- return fileURLToPath(new URL('../guidance/AGENTS.md', import.meta.url));
8537
+ /**
8538
+ * Without --tools, keep the coding tools the project already has guidance
8539
+ * for; a project without any gets all of them.
8540
+ */
8541
+ async function existingGuidanceTools(workspaceRoot) {
8542
+ try {
8543
+ const installed = await installedGuidanceTools(workspaceRoot, await resolveProjectGuidance(workspaceRoot));
8544
+ return installed.length > 0 ? installed : [...SUPPORTED_AI_TOOLS];
8545
+ }
8546
+ catch {
8547
+ return [...SUPPORTED_AI_TOOLS];
8548
+ }
7447
8549
  }
7448
8550
  async function syncInstructions(workspaceRoot, tools) {
7449
- const created = [];
7450
- const agentsPath = path.join(workspaceRoot, AGENTS_FILE);
7451
- if (!existsSync(agentsPath)) {
7452
- await copyFile(bundledAgentsPath(), agentsPath);
7453
- created.push(AGENTS_FILE);
8551
+ try {
8552
+ const source = await resolveProjectGuidance(workspaceRoot);
8553
+ const result = await syncAgentGuidance({
8554
+ projectRoot: workspaceRoot,
8555
+ source,
8556
+ tools,
8557
+ });
8558
+ return {
8559
+ status: 'synced',
8560
+ version: result.version,
8561
+ origin: result.origin,
8562
+ changed: result.changed,
8563
+ skipped: result.skipped.map((entry) => entry.path),
8564
+ };
7454
8565
  }
7455
- if (tools.includes('claude')) {
7456
- const claudePath = path.join(workspaceRoot, CLAUDE_FILE);
7457
- const nestedClaudePath = path.join(workspaceRoot, '.claude', CLAUDE_FILE);
7458
- if (!existsSync(claudePath) && !existsSync(nestedClaudePath)) {
7459
- await writeFile(claudePath, '@AGENTS.md\n\n# Claude Code\n\nUse matching project skills under `.claude/skills/`.\n');
7460
- created.push(CLAUDE_FILE);
8566
+ catch (error) {
8567
+ if (error instanceof GuidanceSourceError) {
8568
+ return {
8569
+ status: 'unavailable',
8570
+ code: error.code,
8571
+ message: error.message,
8572
+ };
7461
8573
  }
8574
+ throw error;
7462
8575
  }
7463
- return created;
7464
8576
  }
7465
8577
  async function syncAgentAdapters({ workspaceRoot, tools, command, args, }) {
7466
8578
  const normalizedWorkspaceRoot = normalizeWorkspaceRoot(workspaceRoot);
7467
8579
  const appliedTools = tools ?? [...SUPPORTED_AI_TOOLS];
8580
+ // Decide which tools get guidance before the MCP files below exist.
8581
+ const guidanceTools = tools ?? (await existingGuidanceTools(normalizedWorkspaceRoot));
7468
8582
  const result = await syncMcpAdapters({
7469
8583
  workspaceRoot: normalizedWorkspaceRoot,
7470
8584
  tools: appliedTools,
7471
8585
  command,
7472
8586
  args,
7473
8587
  });
7474
- const createdInstructions = await syncInstructions(normalizedWorkspaceRoot, appliedTools);
7475
8588
  await Promise.all([
7476
8589
  ...(appliedTools.includes('claude')
7477
8590
  ? [syncClaudeSettings(normalizedWorkspaceRoot, result.serverNames)]
@@ -7483,7 +8596,9 @@ async function syncAgentAdapters({ workspaceRoot, tools, command, args, }) {
7483
8596
  ? [syncOpenCodeSkillPermissions(normalizedWorkspaceRoot)]
7484
8597
  : []),
7485
8598
  ]);
7486
- return { ...result, createdInstructions };
8599
+ // After the settings writes above: guidance also edits .claude/settings.json.
8600
+ const guidance = await syncInstructions(normalizedWorkspaceRoot, guidanceTools);
8601
+ return { ...result, guidance };
7487
8602
  }
7488
8603
  async function pruneAgentAdapters({ workspaceRoot, tools, }) {
7489
8604
  const normalizedWorkspaceRoot = normalizeWorkspaceRoot(workspaceRoot);
@@ -7521,7 +8636,7 @@ async function hasClaudePermissions(workspaceRoot, serverNames) {
7521
8636
  return false;
7522
8637
  }
7523
8638
  const { value } = await readJsonObject(filePath);
7524
- const allow = isRecord$4(value.permissions) ? value.permissions.allow : null;
8639
+ const allow = isRecord$5(value.permissions) ? value.permissions.allow : null;
7525
8640
  const enabled = value.enabledMcpjsonServers;
7526
8641
  return (Array.isArray(allow) &&
7527
8642
  serverNames.every((name) => allow.includes(managedClaudePermission(name))) &&
@@ -7534,7 +8649,7 @@ async function hasCursorPermissions(workspaceRoot, serverNames) {
7534
8649
  return false;
7535
8650
  }
7536
8651
  const { value } = await readJsonObject(filePath);
7537
- return (isRecord$4(value.autoRun) &&
8652
+ return (isRecord$5(value.autoRun) &&
7538
8653
  Array.isArray(value.autoRun.allow_instructions) &&
7539
8654
  value.autoRun.allow_instructions.includes(cursorAllowInstruction(serverNames)));
7540
8655
  }
@@ -7561,9 +8676,9 @@ async function hasOpenCodePermissions(workspaceRoot, serverNames) {
7561
8676
  }
7562
8677
  const { value } = await readJsonObject(filePath);
7563
8678
  const permission = value.permission;
7564
- return (isRecord$4(permission) &&
8679
+ return (isRecord$5(permission) &&
7565
8680
  serverNames.every((name) => permission[`${name}_*`] === 'allow') &&
7566
- isRecord$4(permission.skill) &&
8681
+ isRecord$5(permission.skill) &&
7567
8682
  permission.skill[OPENCODE_SKILL_PERMISSION] === 'allow');
7568
8683
  }
7569
8684
  async function getAdapterSupportStatus(workspaceRoot, tool, serverNames) {
@@ -7637,7 +8752,7 @@ ${servers}
7637
8752
  * This source code is licensed under the MIT license found in the
7638
8753
  * LICENSE file in the root directory of this source tree.
7639
8754
  */
7640
- function isRecord$3(value) {
8755
+ function isRecord$4(value) {
7641
8756
  return typeof value === 'object' && value !== null && !Array.isArray(value);
7642
8757
  }
7643
8758
  function hasCanonicalManagedAdapterEntry(content) {
@@ -7675,11 +8790,11 @@ function getManagedAdapterContent(content, target) {
7675
8790
  }
7676
8791
  try {
7677
8792
  const parsed = JSON.parse(content);
7678
- if (!isRecord$3(parsed)) {
8793
+ if (!isRecord$4(parsed)) {
7679
8794
  return null;
7680
8795
  }
7681
8796
  const sectionValue = parsed[target.jsonKey ?? 'mcpServers'];
7682
- if (!isRecord$3(sectionValue)) {
8797
+ if (!isRecord$4(sectionValue)) {
7683
8798
  return null;
7684
8799
  }
7685
8800
  const managedEntries = Object.fromEntries(Object.entries(sectionValue).filter(([name]) => ALL_MANAGED_MCP_SERVER_NAMES.includes(name)));
@@ -7754,8 +8869,13 @@ async function resolveWorkspace(io, workspace) {
7754
8869
  }
7755
8870
  async function handleAdapterSync(options, io) {
7756
8871
  const workspaceRoot = await resolveWorkspace(io, options.workspace);
7757
- const tools = resolveAdapterTools(options);
7758
- const result = await syncAgentAdapters({ workspaceRoot, tools });
8872
+ const result = await syncAgentAdapters({
8873
+ workspaceRoot,
8874
+ // Undefined keeps the guidance tools the project already has.
8875
+ tools: typeof options.tools === 'string'
8876
+ ? resolveAdapterTools(options)
8877
+ : undefined,
8878
+ });
7759
8879
  return createSuccess({
7760
8880
  ...result,
7761
8881
  adapters: await readAdapterStatus(workspaceRoot),
@@ -7784,6 +8904,74 @@ async function handleAdapterPrompt(options, io) {
7784
8904
  return null;
7785
8905
  }
7786
8906
 
8907
+ /**
8908
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
8909
+ *
8910
+ * This source code is licensed under the MIT license found in the
8911
+ * LICENSE file in the root directory of this source tree.
8912
+ */
8913
+ function resolveProjectRoot(options, io) {
8914
+ if (typeof options.workspace === 'string') {
8915
+ // An explicit project is used as given; walking up from a mistyped path
8916
+ // would write into whatever package encloses it.
8917
+ const workspace = path.resolve(io.cwd, options.workspace);
8918
+ if (!existsSync(path.join(workspace, 'package.json'))) {
8919
+ throw new Error(`--workspace ${options.workspace} has no package.json. Pass the directory of the project that uses IWSDK.`);
8920
+ }
8921
+ return workspace;
8922
+ }
8923
+ const start = io.cwd;
8924
+ const projectRoot = findGuidanceProjectRoot(start);
8925
+ if (projectRoot == null) {
8926
+ throw new Error(`No package.json found at or above ${start}. Run this command inside the project that uses IWSDK.`);
8927
+ }
8928
+ return projectRoot;
8929
+ }
8930
+ async function runGuidanceSync(options, io, dryRun) {
8931
+ const projectRoot = resolveProjectRoot(options, io);
8932
+ const source = await resolveProjectGuidance(projectRoot);
8933
+ // Without --tools, keep the coding tools the project already has guidance
8934
+ // for; a project without any gets all of them.
8935
+ const installed = typeof options.tools === 'string'
8936
+ ? []
8937
+ : await installedGuidanceTools(projectRoot, source);
8938
+ return syncAgentGuidance({
8939
+ projectRoot,
8940
+ source,
8941
+ tools: installed.length > 0 ? installed : resolveAdapterTools(options),
8942
+ // check reports drift; it never counts edited files as fixable.
8943
+ force: !dryRun && options.force === true,
8944
+ dryRun,
8945
+ });
8946
+ }
8947
+ function skippedHint(result) {
8948
+ if (result.skipped.length === 0) {
8949
+ return [];
8950
+ }
8951
+ return [
8952
+ '',
8953
+ `Left ${result.skipped.length} file(s) alone:`,
8954
+ ...result.skipped.map((entry) => `- ${entry.path}: ${entry.detail ?? (entry.reason === 'unmanaged' ? 'not written by IWSDK.' : 'edited since IWSDK wrote it.')}`),
8955
+ 'Review them against this release. `npx @iwsdk/cli@latest agents sync --force` replaces edited and unmanaged files.',
8956
+ ];
8957
+ }
8958
+ async function handleAgentsSync(options, io) {
8959
+ const result = await runGuidanceSync(options, io, false);
8960
+ // Coding agents read stderr too; this is the one channel that reaches the
8961
+ // session that just installed the guidance.
8962
+ io.stderr.write(`${[result.agentNotice, ...skippedHint(result)].join('\n')}\n`);
8963
+ return createSuccess(result);
8964
+ }
8965
+ async function handleAgentsCheck(options, io) {
8966
+ const result = await runGuidanceSync(options, io, true);
8967
+ // Edited files are the developer's choice; only fail on what sync would fix.
8968
+ const drift = result.results.filter((entry) => entry.action !== 'unchanged' && entry.action !== 'skipped');
8969
+ if (drift.length === 0) {
8970
+ return createSuccess(result);
8971
+ }
8972
+ return createFailure(`Agent guidance differs from IWSDK ${result.version} in ${drift.length} place(s). Run \`npx @iwsdk/cli agents sync\`.`, 'agent_guidance_drift', { projectRoot: result.projectRoot, version: result.version, drift });
8973
+ }
8974
+
7787
8975
  var bufferUtil$1 = {exports: {}};
7788
8976
 
7789
8977
  const BINARY_TYPES$2 = ['nodebuffer', 'arraybuffer', 'fragments'];
@@ -12086,7 +13274,7 @@ function getProtocolOrder(runtimeSession) {
12086
13274
  }
12087
13275
  return ['wss', 'ws'];
12088
13276
  }
12089
- function isRecord$2(value) {
13277
+ function isRecord$3(value) {
12090
13278
  return value != null && typeof value === 'object' && !Array.isArray(value);
12091
13279
  }
12092
13280
  const PERMISSION_FAILURE = /permission|not permitted|denied|sandbox|eacces|eperm/i;
@@ -12414,14 +13602,14 @@ async function sendRuntimeCommandBeforeDeadline(options, deadline) {
12414
13602
  }
12415
13603
  }
12416
13604
  function sceneOpenReadinessRequest(method, params, response, previousSceneSessionId) {
12417
- if (method !== 'scene_open' || !isRecord$2(response.result)) {
13605
+ if (method !== 'scene_open' || !isRecord$3(response.result)) {
12418
13606
  return null;
12419
13607
  }
12420
13608
  const result = response.result;
12421
13609
  if (result.reloading !== true || result.ready === true) {
12422
13610
  return null;
12423
13611
  }
12424
- const request = isRecord$2(params) ? params : {};
13612
+ const request = isRecord$3(params) ? params : {};
12425
13613
  const scenePath = typeof result.path === 'string'
12426
13614
  ? result.path
12427
13615
  : typeof request.path === 'string'
@@ -12454,8 +13642,8 @@ async function captureSceneOpenSessionBaseline(options, deadline) {
12454
13642
  target: { role: 'editor' },
12455
13643
  }, deadline);
12456
13644
  const state = stateResponse.result;
12457
- return isRecord$2(state) &&
12458
- isRecord$2(state.editor) &&
13645
+ return isRecord$3(state) &&
13646
+ isRecord$3(state.editor) &&
12459
13647
  typeof state.editor.sceneSessionId === 'string'
12460
13648
  ? state.editor.sceneSessionId
12461
13649
  : null;
@@ -12473,7 +13661,7 @@ async function captureSceneOpenSessionBaseline(options, deadline) {
12473
13661
  });
12474
13662
  }
12475
13663
  function editorReadyForOpenedScene(state, scenePath, previousSceneSessionId) {
12476
- if (!isRecord$2(state) || !isRecord$2(state.editor)) {
13664
+ if (!isRecord$3(state) || !isRecord$3(state.editor)) {
12477
13665
  return null;
12478
13666
  }
12479
13667
  const editor = state.editor;
@@ -12727,6 +13915,33 @@ function serializeRunnerResult(value) {
12727
13915
  }
12728
13916
  return JSON.parse(serialized);
12729
13917
  }
13918
+ /**
13919
+ * Run `fn` with the managed app drawing every frame, then release the hold,
13920
+ * also when `fn` throws. Apps without render holds (non-IWSDK runtimes, older
13921
+ * @iwsdk/core) always draw continuously, so `fn` simply runs.
13922
+ */
13923
+ async function withRenderHold(frame, fn) {
13924
+ const id = await frame
13925
+ .evaluate(() => {
13926
+ const runtime = globalThis.FRAMEWORK_MCP_RUNTIME;
13927
+ return typeof runtime?.acquireRenderHold === 'function'
13928
+ ? runtime.acquireRenderHold()
13929
+ : null;
13930
+ }, undefined)
13931
+ .catch(() => null);
13932
+ try {
13933
+ return await fn();
13934
+ }
13935
+ finally {
13936
+ if (id != null) {
13937
+ await frame
13938
+ .evaluate((holdId) => {
13939
+ globalThis.FRAMEWORK_MCP_RUNTIME?.releaseRenderHold?.(holdId);
13940
+ }, id)
13941
+ .catch(() => { });
13942
+ }
13943
+ }
13944
+ }
12730
13945
  async function handleBrowserRun(scriptArgument, options, io) {
12731
13946
  if (!scriptArgument) {
12732
13947
  throw new Error('Usage: iwsdk browser run <workspace-script.mjs>');
@@ -12865,15 +14080,18 @@ async function handleBrowserRun(scriptArgument, options, io) {
12865
14080
  if (typeof run !== 'function') {
12866
14081
  throw new Error('browser run script must export a default async function or named run function');
12867
14082
  }
12868
- const result = await run({
14083
+ // Scripts may capture pixels themselves (page.screenshot), which the
14084
+ // managed session's on-demand rendering would leave stale.
14085
+ const appFrame = frame ?? page.mainFrame();
14086
+ const result = await withRenderHold(appFrame, async () => run({
12869
14087
  browser,
12870
14088
  cdp,
12871
14089
  context,
12872
- frame: frame ?? page.mainFrame(),
14090
+ frame: appFrame,
12873
14091
  page,
12874
14092
  signal: abortController.signal,
12875
14093
  workspaceRoot,
12876
- });
14094
+ }));
12877
14095
  return createSuccess({
12878
14096
  operation: 'browser.run',
12879
14097
  result: serializeRunnerResult(result),
@@ -12906,23 +14124,482 @@ async function handleBrowserRun(scriptArgument, options, io) {
12906
14124
  });
12907
14125
  }
12908
14126
  }
12909
- finally {
12910
- if (cleanup.detachCdp != null) {
12911
- try {
12912
- await cleanup.detachCdp();
12913
- }
12914
- catch { }
14127
+ finally {
14128
+ if (cleanup.detachCdp != null) {
14129
+ try {
14130
+ await cleanup.detachCdp();
14131
+ }
14132
+ catch { }
14133
+ }
14134
+ try {
14135
+ await disconnectBrowser();
14136
+ }
14137
+ catch { }
14138
+ if (runnerSettled) {
14139
+ lease?.release();
14140
+ }
14141
+ else {
14142
+ lease?.abandon();
14143
+ }
14144
+ }
14145
+ }
14146
+
14147
+ /**
14148
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
14149
+ *
14150
+ * This source code is licensed under the MIT license found in the
14151
+ * LICENSE file in the root directory of this source tree.
14152
+ */
14153
+ const MIGRATION_GUIDES = [
14154
+ {
14155
+ id: 'iwsdk-migrate-0-5',
14156
+ introducedIn: '0.5.0',
14157
+ summary: 'native scene JSON replaces GLXF, the managed editor replaces the external scene editor, retired Vite plugins removed, UIKitML loads at runtime',
14158
+ },
14159
+ ];
14160
+ const MIGRATIONS_DIRECTORY = '.iwsdk/migrations';
14161
+ /** Guides for every release boundary in (from, to], oldest first. */
14162
+ function migrationsBetween(from, to) {
14163
+ const fromVersion = from
14164
+ ? semver$1.coerce(from, { includePrerelease: true })
14165
+ : null;
14166
+ const toVersion = semver$1.coerce(to, { includePrerelease: true });
14167
+ if (fromVersion == null || toVersion == null) {
14168
+ return [];
14169
+ }
14170
+ return MIGRATION_GUIDES.filter((guide) => semver$1.lt(fromVersion, guide.introducedIn) &&
14171
+ semver$1.gte(toVersion, guide.introducedIn)).sort((left, right) => semver$1.compare(left.introducedIn, right.introducedIn));
14172
+ }
14173
+ function bundledMigrationPath(id) {
14174
+ // dist/cli.js reads dist/migrations; source runs (tests) read the build.
14175
+ const candidates = [
14176
+ new URL(`./migrations/${id}/SKILL.md`, import.meta.url),
14177
+ new URL(`../dist/migrations/${id}/SKILL.md`, import.meta.url),
14178
+ ].map((url) => fileURLToPath(url));
14179
+ return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
14180
+ }
14181
+ /**
14182
+ * Write the guides into the project's ignored .iwsdk/ directory, where an
14183
+ * agent can read them during the upgrade without them becoming project skills
14184
+ * that trigger long after it.
14185
+ */
14186
+ async function materializeMigrations(projectRoot, guides) {
14187
+ const written = [];
14188
+ for (const guide of guides) {
14189
+ const relativePath = `${MIGRATIONS_DIRECTORY}/${guide.id}/SKILL.md`;
14190
+ const target = path.join(projectRoot, relativePath);
14191
+ await mkdir(path.dirname(target), { recursive: true });
14192
+ await writeFile(target, await readFile(bundledMigrationPath(guide.id)));
14193
+ written.push({ ...guide, path: relativePath });
14194
+ }
14195
+ if (written.length > 0) {
14196
+ await ensureIwsdkDirectoryIgnored(projectRoot);
14197
+ }
14198
+ return written;
14199
+ }
14200
+ /** Add .iwsdk/ to the project's .gitignore unless it is already there. */
14201
+ async function ensureIwsdkDirectoryIgnored(projectRoot) {
14202
+ const gitignorePath = path.join(projectRoot, '.gitignore');
14203
+ const current = existsSync(gitignorePath)
14204
+ ? await readFile(gitignorePath, 'utf8')
14205
+ : '';
14206
+ const lines = current.split(/\r?\n/u).map((line) => line.trim());
14207
+ if (lines.includes('.iwsdk/') || lines.includes('.iwsdk')) {
14208
+ return;
14209
+ }
14210
+ await appendFile(gitignorePath, `${current && !current.endsWith('\n') ? '\n' : ''}.iwsdk/\n`);
14211
+ }
14212
+ function formatMigrationNotice(from, to, migrations) {
14213
+ if (migrations.length === 0) {
14214
+ return '';
14215
+ }
14216
+ return [
14217
+ `IWSDK ${from ?? 'an earlier release'} -> ${to} crosses ${migrations.length === 1 ? 'a release that needs' : 'releases that need'} code changes. Follow ${migrations.length === 1 ? 'this guide' : 'these guides, in order,'} before other work:`,
14218
+ ...migrations.map((migration) => `- ${migration.path} (${migration.introducedIn}: ${migration.summary})`),
14219
+ ].join('\n');
14220
+ }
14221
+
14222
+ /**
14223
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
14224
+ *
14225
+ * This source code is licensed under the MIT license found in the
14226
+ * LICENSE file in the root directory of this source tree.
14227
+ */
14228
+ const LOCKFILES = [
14229
+ ['pnpm-lock.yaml', 'pnpm'],
14230
+ ['yarn.lock', 'yarn'],
14231
+ ['bun.lock', 'bun'],
14232
+ ['bun.lockb', 'bun'],
14233
+ ['package-lock.json', 'npm'],
14234
+ ['npm-shrinkwrap.json', 'npm'],
14235
+ ];
14236
+ function declaredPackageManager(directory) {
14237
+ try {
14238
+ const manifest = JSON.parse(readFileSync(path.join(directory, 'package.json'), 'utf8'));
14239
+ const name = typeof manifest.packageManager === 'string'
14240
+ ? manifest.packageManager.split('@')[0]
14241
+ : '';
14242
+ return name === 'npm' ||
14243
+ name === 'pnpm' ||
14244
+ name === 'yarn' ||
14245
+ name === 'bun'
14246
+ ? name
14247
+ : null;
14248
+ }
14249
+ catch {
14250
+ return null;
14251
+ }
14252
+ }
14253
+ /**
14254
+ * True for a pnpm-workspace.yaml that lists packages besides the directory
14255
+ * itself. Generated apps carry one with `packages: ['.']` whatever their
14256
+ * package manager, so that one says nothing.
14257
+ */
14258
+ function isPnpmWorkspace(directory) {
14259
+ let text;
14260
+ try {
14261
+ text = readFileSync(path.join(directory, 'pnpm-workspace.yaml'), 'utf8');
14262
+ }
14263
+ catch {
14264
+ return false;
14265
+ }
14266
+ // `packages: [a, b]` or a block list under `packages:`.
14267
+ const lines = text.split(/\r?\n/u);
14268
+ const start = lines.findIndex((line) => /^packages\s*:/u.test(line));
14269
+ if (start === -1) {
14270
+ return false;
14271
+ }
14272
+ const inline = lines[start].replace(/^packages\s*:/u, '').trim();
14273
+ const entries = inline.startsWith('[')
14274
+ ? inline.replace(/^\[|\].*$/gu, '').split(',')
14275
+ : lines
14276
+ .slice(start + 1)
14277
+ .filter((line) => !/^\s*(?:#.*)?$/u.test(line))
14278
+ .filter((_, index, rest) => rest.slice(0, index + 1).every((line) => /^\s+-/u.test(line)))
14279
+ .map((line) => line.replace(/^\s+-/u, ''));
14280
+ return entries
14281
+ .map((entry) => entry
14282
+ .replace(/#.*$/u, '')
14283
+ .trim()
14284
+ .replace(/^['"]|['"]$/gu, ''))
14285
+ .some((entry) => entry !== '' && entry !== '.' && entry !== './');
14286
+ }
14287
+ /** A directory whose package.json declares workspaces, or a pnpm workspace. */
14288
+ function isWorkspaceRoot(directory) {
14289
+ try {
14290
+ const manifest = JSON.parse(readFileSync(path.join(directory, 'package.json'), 'utf8'));
14291
+ if (manifest.workspaces != null) {
14292
+ return true;
14293
+ }
14294
+ }
14295
+ catch {
14296
+ // No readable package.json; pnpm keeps its workspace list elsewhere.
14297
+ }
14298
+ return isPnpmWorkspace(directory);
14299
+ }
14300
+ /**
14301
+ * The package manager a project uses: the nearest lockfile at or above it, so
14302
+ * an app inside a monorepo uses the monorepo's tool and lockfile, with the
14303
+ * nearest `packageManager` field taking precedence. Without a lockfile, the
14304
+ * field or a pnpm workspace decides. Stops at the repository root.
14305
+ */
14306
+ function findPackageManager(projectRoot) {
14307
+ const start = path.resolve(projectRoot);
14308
+ let declared = null;
14309
+ let workspace = null;
14310
+ let current = start;
14311
+ while (true) {
14312
+ if (current === start || isWorkspaceRoot(current)) {
14313
+ declared ??= declaredPackageManager(current);
14314
+ }
14315
+ if (workspace == null && isPnpmWorkspace(current)) {
14316
+ workspace = current;
14317
+ }
14318
+ const lockfile = LOCKFILES.find(([name]) => existsSync(path.join(current, name)));
14319
+ // Above the project, a lockfile counts only at a workspace root; a stray
14320
+ // ~/package-lock.json does not make the home folder a monorepo.
14321
+ if (lockfile && (current === start || isWorkspaceRoot(current))) {
14322
+ return {
14323
+ name: declared ?? lockfile[1],
14324
+ root: current,
14325
+ lockfile: path.join(current, lockfile[0]),
14326
+ };
14327
+ }
14328
+ const parent = path.dirname(current);
14329
+ if (existsSync(path.join(current, '.git')) || parent === current) {
14330
+ if (declared == null && workspace != null) {
14331
+ return { name: 'pnpm', root: workspace, lockfile: null };
14332
+ }
14333
+ return { name: declared ?? 'npm', root: start, lockfile: null };
14334
+ }
14335
+ current = parent;
14336
+ }
14337
+ }
14338
+ /**
14339
+ * The @iwsdk/core version the lockfile resolves for this project, or null
14340
+ * when there is no lockfile this can read. Handles workspace lockfiles, where
14341
+ * the project is one importer among several.
14342
+ */
14343
+ function readLockedCoreVersion(projectRoot) {
14344
+ const { lockfile, root } = findPackageManager(projectRoot);
14345
+ if (lockfile == null || !existsSync(lockfile)) {
14346
+ return null;
14347
+ }
14348
+ const text = readFileSync(lockfile, 'utf8');
14349
+ const relative = path
14350
+ .relative(root, path.resolve(projectRoot))
14351
+ .split(path.sep)
14352
+ .join('/');
14353
+ if (lockfile.endsWith('package-lock.json') ||
14354
+ lockfile.endsWith('npm-shrinkwrap.json')) {
14355
+ try {
14356
+ const packages = JSON.parse(text).packages ?? {};
14357
+ return ((relative &&
14358
+ packages[`${relative}/node_modules/@iwsdk/core`]?.version) ||
14359
+ packages['node_modules/@iwsdk/core']?.version ||
14360
+ null);
14361
+ }
14362
+ catch {
14363
+ return null;
14364
+ }
14365
+ }
14366
+ if (lockfile.endsWith('pnpm-lock.yaml')) {
14367
+ // importers:\n <project>:\n dependencies:\n '@iwsdk/core':\n specifier: …\n version: …
14368
+ const importer = relative || '.';
14369
+ const lines = text.split(/\r?\n/u);
14370
+ const start = lines.findIndex((line) => line === ` ${importer}:` ||
14371
+ line === ` '${importer}':` ||
14372
+ line === ` "${importer}":`);
14373
+ if (start === -1) {
14374
+ return null;
14375
+ }
14376
+ for (let index = start + 1; index < lines.length; index++) {
14377
+ if (/^ {2}\S/u.test(lines[index])) {
14378
+ break;
14379
+ }
14380
+ if (/^ {6}'@iwsdk\/core':$/u.test(lines[index])) {
14381
+ for (let next = index + 1; next < index + 4 && next < lines.length; next++) {
14382
+ const version = lines[next].match(/^ {8}version: ([^\s(]+)/u)?.[1];
14383
+ if (version) {
14384
+ return version;
14385
+ }
14386
+ }
14387
+ }
14388
+ }
14389
+ return null;
14390
+ }
14391
+ if (lockfile.endsWith('yarn.lock')) {
14392
+ return (text.match(/^"?@iwsdk\/core@[^\n]*:\r?\n {2}version:? "?([^"\s]+)"?/mu)?.[1] ?? null);
14393
+ }
14394
+ return null;
14395
+ }
14396
+
14397
+ /**
14398
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
14399
+ *
14400
+ * This source code is licensed under the MIT license found in the
14401
+ * LICENSE file in the root directory of this source tree.
14402
+ */
14403
+ const RELEASE_NOTES_PATH = '.iwsdk/migrations/release-notes.md';
14404
+ function loadReleaseNotes() {
14405
+ // dist/cli.js reads dist/release-notes.json; source runs (tests) read the build.
14406
+ for (const candidate of [
14407
+ new URL('./release-notes.json', import.meta.url),
14408
+ new URL('../dist/release-notes.json', import.meta.url),
14409
+ ].map((url) => fileURLToPath(url))) {
14410
+ if (existsSync(candidate)) {
14411
+ return JSON.parse(readFileSync(candidate, 'utf8')).entries;
14412
+ }
14413
+ }
14414
+ return [];
14415
+ }
14416
+ /** Entries for every release in (from, to], oldest first. */
14417
+ function releaseNotesBetween(from, to, notes = loadReleaseNotes()) {
14418
+ if (from == null || semver$1.valid(from) == null || semver$1.valid(to) == null) {
14419
+ return [];
14420
+ }
14421
+ const seen = new Set();
14422
+ return (notes
14423
+ .filter((note) => semver$1.valid(note.version) != null &&
14424
+ semver$1.gt(note.version, from) &&
14425
+ semver$1.lte(note.version, to))
14426
+ .sort((left, right) => semver$1.compare(left.version, right.version))
14427
+ // A stable release repeats its prereleases' entries; keep the first.
14428
+ .filter((note) => !seen.has(note.text) && Boolean(seen.add(note.text))));
14429
+ }
14430
+ function formatReleaseNotes(from, to, notes) {
14431
+ const lines = [
14432
+ `# IWSDK release notes: ${from} -> ${to}`,
14433
+ '',
14434
+ 'Every change released after the version this project used, oldest first. Major and minor changes are the ones most likely to need app changes; migration guides in this folder take precedence.',
14435
+ ];
14436
+ let version = null;
14437
+ for (const note of notes) {
14438
+ if (note.version !== version) {
14439
+ version = note.version;
14440
+ lines.push('', `## ${version}`, '');
14441
+ }
14442
+ const text = note.text.replace(/\n/gu, '\n ');
14443
+ lines.push(`- **${note.kind}** (${note.packages.map((name) => name.replace('@iwsdk/', '')).join(', ')}): ${text}`);
14444
+ }
14445
+ return `${lines.join('\n')}\n`;
14446
+ }
14447
+ async function writeReleaseNotes(projectRoot, from, to) {
14448
+ const notes = releaseNotesBetween(from, to);
14449
+ if (from == null || notes.length === 0) {
14450
+ return null;
14451
+ }
14452
+ const target = path.join(projectRoot, RELEASE_NOTES_PATH);
14453
+ await mkdir(path.dirname(target), { recursive: true });
14454
+ await writeFile(target, formatReleaseNotes(from, to, notes));
14455
+ await ensureIwsdkDirectoryIgnored(projectRoot);
14456
+ return {
14457
+ path: RELEASE_NOTES_PATH,
14458
+ count: notes.length,
14459
+ notable: notes.filter((note) => note.kind !== 'patch').length,
14460
+ };
14461
+ }
14462
+ function formatReleaseNotesNotice(from, to, written) {
14463
+ return written
14464
+ ? `What changed from ${from} to ${to}: ${written.path} (${written.count} entries, ${written.notable} major or minor).`
14465
+ : '';
14466
+ }
14467
+
14468
+ /**
14469
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
14470
+ *
14471
+ * This source code is licensed under the MIT license found in the
14472
+ * LICENSE file in the root directory of this source tree.
14473
+ */
14474
+ function readManifestMode(projectRoot) {
14475
+ try {
14476
+ const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'iwsdk.config.json'), 'utf8'));
14477
+ const mode = manifest.dev?.agentGuidance;
14478
+ return mode === 'auto' || mode === 'warn' || mode === 'off' ? mode : null;
14479
+ }
14480
+ catch {
14481
+ return null;
14482
+ }
14483
+ }
14484
+ function resolveAgentGuidanceMode(projectRoot, env = process.env) {
14485
+ const fromEnv = env.IWSDK_AGENT_GUIDANCE;
14486
+ if (fromEnv === 'auto' || fromEnv === 'warn' || fromEnv === 'off') {
14487
+ return fromEnv;
14488
+ }
14489
+ return readManifestMode(projectRoot) ?? 'auto';
14490
+ }
14491
+ /** The release recorded in the project's AGENTS.md guidance block. */
14492
+ function readGuidanceVersion(projectRoot) {
14493
+ try {
14494
+ const agents = readFileSync(path.join(projectRoot, 'AGENTS.md'), 'utf8');
14495
+ return (agents.match(/<!-- BEGIN iwsdk-agent-guidance version=(\S+) /u)?.[1] ??
14496
+ null);
14497
+ }
14498
+ catch {
14499
+ return null;
14500
+ }
14501
+ }
14502
+ /**
14503
+ * Called by `iwsdk dev up`/`restart`. When the installed @iwsdk/core ships
14504
+ * different guidance than the project has, refresh the files nobody edited,
14505
+ * or report it when refreshing is not safe. Never throws.
14506
+ */
14507
+ async function refreshAgentGuidanceForDev(projectRoot, env = process.env) {
14508
+ try {
14509
+ const mode = resolveAgentGuidanceMode(projectRoot, env);
14510
+ if (mode === 'off') {
14511
+ return null;
12915
14512
  }
12916
- try {
12917
- await disconnectBrowser();
14513
+ const source = await resolveProjectGuidance(projectRoot);
14514
+ if (source.origin !== 'installed-core') {
14515
+ return null;
12918
14516
  }
12919
- catch { }
12920
- if (runnerSettled) {
12921
- lease?.release();
14517
+ const version = source.manifest.version;
14518
+ const previousVersion = readGuidanceVersion(projectRoot);
14519
+ // Refresh only the coding tools this project already has guidance for:
14520
+ // a project synced with `--tools claude` must not gain Cursor rules.
14521
+ const tools = await installedGuidanceTools(projectRoot, source);
14522
+ if (tools.length === 0) {
14523
+ // Guidance was never installed here; adding it is the developer's call.
14524
+ return {
14525
+ action: 'missing',
14526
+ previousVersion,
14527
+ version,
14528
+ changed: [],
14529
+ skipped: [],
14530
+ migrations: [],
14531
+ notice: `[IWSDK] This project has no IWSDK ${version} coding-agent guidance. Run \`npx @iwsdk/cli@latest agents sync\` to install it.`,
14532
+ };
12922
14533
  }
12923
- else {
12924
- lease?.abandon();
14534
+ const plan = await syncAgentGuidance({
14535
+ projectRoot,
14536
+ source,
14537
+ tools,
14538
+ dryRun: true,
14539
+ });
14540
+ if (!plan.changed) {
14541
+ return null;
14542
+ }
14543
+ const locked = readLockedCoreVersion(projectRoot);
14544
+ const installed = readInstalledCoreVersion(projectRoot);
14545
+ const reason = mode === 'warn'
14546
+ ? 'mode-warn'
14547
+ : env.CI
14548
+ ? 'ci'
14549
+ : locked != null && installed != null && locked !== installed
14550
+ ? 'lockfile-mismatch'
14551
+ : undefined;
14552
+ const changed = plan.results.filter((result) => result.action !== 'unchanged' && result.action !== 'skipped');
14553
+ if (reason) {
14554
+ return {
14555
+ action: 'stale',
14556
+ previousVersion,
14557
+ version,
14558
+ reason,
14559
+ changed,
14560
+ skipped: plan.skipped,
14561
+ migrations: [],
14562
+ notice: reason === 'lockfile-mismatch'
14563
+ ? `[IWSDK] node_modules has @iwsdk/core ${installed} but the lockfile resolves ${locked}; agent guidance was not refreshed. Run your package manager's install.`
14564
+ : `[IWSDK] Coding-agent guidance differs from the installed IWSDK ${version} in ${changed.length} place(s). Run \`npx @iwsdk/cli@latest agents sync\`.`,
14565
+ };
12925
14566
  }
14567
+ const result = await syncAgentGuidance({ projectRoot, source, tools });
14568
+ const applied = result.results.filter((entry) => entry.action !== 'unchanged' && entry.action !== 'skipped');
14569
+ const migrations = await materializeMigrations(projectRoot, migrationsBetween(previousVersion, version));
14570
+ const releaseNotes = previousVersion && previousVersion !== version
14571
+ ? await writeReleaseNotes(projectRoot, previousVersion, version)
14572
+ : null;
14573
+ const migrationNotice = [
14574
+ formatMigrationNotice(previousVersion, version, migrations),
14575
+ formatReleaseNotesNotice(previousVersion, version, releaseNotes),
14576
+ ]
14577
+ .filter(Boolean)
14578
+ .join('\n');
14579
+ return {
14580
+ action: 'refreshed',
14581
+ previousVersion,
14582
+ version,
14583
+ changed: applied,
14584
+ skipped: result.skipped,
14585
+ migrations,
14586
+ notice: [
14587
+ `[IWSDK] Updated coding-agent guidance${previousVersion ? ` from ${previousVersion}` : ''} to the installed IWSDK ${version}: ${applied
14588
+ .map((entry) => entry.path)
14589
+ .join(', ')}.`,
14590
+ 'Agents: re-read the iwsdk-agent-guidance block in AGENTS.md and any changed skill before continuing.',
14591
+ ...(result.skipped.length > 0
14592
+ ? [
14593
+ `Left edited files alone: ${result.skipped.map((entry) => entry.path).join(', ')} (\`npx @iwsdk/cli@latest agents sync --force\` replaces them).`,
14594
+ ]
14595
+ : []),
14596
+ ...(migrationNotice ? [migrationNotice] : []),
14597
+ ].join('\n'),
14598
+ };
14599
+ }
14600
+ catch {
14601
+ // Guidance upkeep must never stop the dev server from starting.
14602
+ return null;
12926
14603
  }
12927
14604
  }
12928
14605
 
@@ -13104,17 +14781,8 @@ async function detectPackageManager(workspaceRoot) {
13104
14781
  if (typeof packageJson.packageManager === 'string') {
13105
14782
  return packageJson.packageManager.split('@')[0];
13106
14783
  }
13107
- if (existsSync(path.join(workspaceRoot, 'pnpm-lock.yaml'))) {
13108
- return 'pnpm';
13109
- }
13110
- if (existsSync(path.join(workspaceRoot, 'yarn.lock'))) {
13111
- return 'yarn';
13112
- }
13113
- if (existsSync(path.join(workspaceRoot, 'bun.lockb')) ||
13114
- existsSync(path.join(workspaceRoot, 'bun.lock'))) {
13115
- return 'bun';
13116
- }
13117
- return 'npm';
14784
+ // The nearest lockfile, so an app inside a monorepo uses its tool.
14785
+ return findPackageManager(workspaceRoot).name;
13118
14786
  }
13119
14787
  async function resolveDevRuntimeScript(workspaceRoot) {
13120
14788
  const packageJson = await readPackageManifest(workspaceRoot);
@@ -13545,12 +15213,52 @@ async function terminateRuntimeWorkspace(workspaceRoot) {
13545
15213
  };
13546
15214
  }
13547
15215
  async function handleDevUp(options, io) {
13548
- const devSessionOptions = resolveDevSessionOptions(options);
13549
15216
  const workspaceRoot = await resolveWorkspaceRoot({
13550
15217
  cwd: io.cwd,
13551
15218
  workspace: typeof options.workspace === 'string' ? options.workspace : undefined,
13552
15219
  requireRunning: false,
13553
15220
  });
15221
+ // Coding agents start the dev server right after upgrading IWSDK; this is
15222
+ // where guidance from the previous release gets noticed and refreshed.
15223
+ // Foreground output is plain text; otherwise the report joins the JSON.
15224
+ const agentGuidance = await refreshAgentGuidanceForDev(workspaceRoot);
15225
+ if (agentGuidance && isForegroundLaunch(options)) {
15226
+ io.stdout.write(`${agentGuidance.notice}\n`);
15227
+ }
15228
+ let result;
15229
+ try {
15230
+ result = await startOrAttachDevRuntime(options, io, workspaceRoot);
15231
+ }
15232
+ catch (error) {
15233
+ // The CLI turns this into the failure JSON; carry the report along.
15234
+ if (agentGuidance && error instanceof Error) {
15235
+ Object.assign(error, { agentGuidance });
15236
+ }
15237
+ throw error;
15238
+ }
15239
+ if (agentGuidance && result && typeof result === 'object') {
15240
+ if (result.ok) {
15241
+ return createSuccess({
15242
+ ...result.data,
15243
+ agentGuidance,
15244
+ });
15245
+ }
15246
+ // The refresh already ran; say so even though the server did not start.
15247
+ return {
15248
+ ...result,
15249
+ error: {
15250
+ ...result.error,
15251
+ details: {
15252
+ ...(result.error.details ?? {}),
15253
+ agentGuidance,
15254
+ },
15255
+ },
15256
+ };
15257
+ }
15258
+ return result;
15259
+ }
15260
+ async function startOrAttachDevRuntime(options, io, workspaceRoot) {
15261
+ const devSessionOptions = resolveDevSessionOptions(options);
13554
15262
  const timeoutMs = parseIntegerOption(options.timeout, '--timeout', 60000);
13555
15263
  const foreground = isForegroundLaunch(options);
13556
15264
  const openBrowser = devSessionOptions.open;
@@ -31073,6 +32781,20 @@ const ISSUE_CAUSES = {
31073
32781
  open_failed: true,
31074
32782
  };
31075
32783
  const KNOWN_ISSUE_CAUSES = new Set(Object.keys(ISSUE_CAUSES));
32784
+ const HOST_ERROR_CODES = {
32785
+ command_timeout: true,
32786
+ browser_command_timeout: true,
32787
+ browser_command_busy: true,
32788
+ browser_command_queue_timeout: true,
32789
+ target_not_ready: true,
32790
+ target_unavailable: true,
32791
+ ambiguous_target: true,
32792
+ stale_browser_tab: true,
32793
+ runtime_busy: true,
32794
+ runtime_stopping: true,
32795
+ unsupported_on_target: true,
32796
+ };
32797
+ const KNOWN_HOST_ERROR_CODES = new Set(Object.keys(HOST_ERROR_CODES));
31076
32798
  /** Maps an error from resolving or running an operation to its reason. */
31077
32799
  function getRuntimeFailureReason(error) {
31078
32800
  if (error instanceof WorkspaceResolutionError) {
@@ -31082,7 +32804,14 @@ function getRuntimeFailureReason(error) {
31082
32804
  // The runtime forwards a string cause from whatever the app threw, so
31083
32805
  // only the known causes are reported.
31084
32806
  const cause = error.issueCause;
31085
- return cause && KNOWN_ISSUE_CAUSES.has(cause) ? cause : 'runtime_error';
32807
+ if (cause && KNOWN_ISSUE_CAUSES.has(cause)) {
32808
+ return cause;
32809
+ }
32810
+ const code = error.details?.code;
32811
+ return typeof code === 'string' &&
32812
+ (KNOWN_HOST_ERROR_CODES.has(code) || KNOWN_ISSUE_CAUSES.has(code))
32813
+ ? code
32814
+ : 'runtime_error';
31086
32815
  }
31087
32816
  return 'unknown';
31088
32817
  }
@@ -31144,19 +32873,19 @@ async function saveScreenshot(result, requestedPath) {
31144
32873
  * This source code is licensed under the MIT license found in the
31145
32874
  * LICENSE file in the root directory of this source tree.
31146
32875
  */
31147
- function isRecord$1(value) {
32876
+ function isRecord$2(value) {
31148
32877
  return typeof value === 'object' && value !== null && !Array.isArray(value);
31149
32878
  }
31150
32879
  const MAX_ASSET_PREVIEW_MCP_NAMED_PARTS = 40;
31151
32880
  const MAX_ASSET_PREVIEW_MCP_WARNINGS = 24;
31152
32881
  const MAX_ASSET_PREVIEW_MCP_WARNINGS_PER_CODE = 3;
31153
32882
  function compactAssetPreviewMetadata(metadata) {
31154
- if (!isRecord$1(metadata.diagnostics)) {
32883
+ if (!isRecord$2(metadata.diagnostics)) {
31155
32884
  return metadata;
31156
32885
  }
31157
32886
  const diagnostics = metadata.diagnostics;
31158
32887
  const namedPartRecords = Array.isArray(diagnostics.namedParts)
31159
- ? diagnostics.namedParts.filter(isRecord$1)
32888
+ ? diagnostics.namedParts.filter(isRecord$2)
31160
32889
  : null;
31161
32890
  const namedParts = (namedPartRecords ?? [])
31162
32891
  .slice(0, MAX_ASSET_PREVIEW_MCP_NAMED_PARTS)
@@ -31169,7 +32898,7 @@ function compactAssetPreviewMetadata(metadata) {
31169
32898
  ? diagnostics.namedPartCount
31170
32899
  : namedPartRecords?.length;
31171
32900
  const warningRecords = Array.isArray(diagnostics.warnings)
31172
- ? diagnostics.warnings.filter(isRecord$1)
32901
+ ? diagnostics.warnings.filter(isRecord$2)
31173
32902
  : null;
31174
32903
  const warningCodeCounts = new Map();
31175
32904
  const warningSampleCounts = new Map();
@@ -31252,7 +32981,7 @@ function createTabTracker() {
31252
32981
  }
31253
32982
  const normalizedResult = Array.isArray(result)
31254
32983
  ? result
31255
- : isRecord$1(result)
32984
+ : isRecord$2(result)
31256
32985
  ? result
31257
32986
  : { value: result };
31258
32987
  if (Array.isArray(normalizedResult)) {
@@ -31282,7 +33011,7 @@ function withBrowserStatus$1(result, session) {
31282
33011
  const browser = session.browser ?? null;
31283
33012
  const browserConnected = Boolean(session.browser?.connected);
31284
33013
  const browserCommandReady = isRuntimeBrowserCommandReady(session);
31285
- if (isRecord$1(result)) {
33014
+ if (isRecord$2(result)) {
31286
33015
  return {
31287
33016
  ...result,
31288
33017
  browser,
@@ -31389,6 +33118,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = CLI_
31389
33118
  : rawResponse;
31390
33119
  const result = normalizedResponse.result ?? normalizedResponse;
31391
33120
  if ((name === 'browser_screenshot' ||
33121
+ name === 'browser_filmstrip' ||
31392
33122
  name === 'scene_screenshot' ||
31393
33123
  name === 'scene_render_file' ||
31394
33124
  name === 'asset_render_preview' ||
@@ -31405,9 +33135,9 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = CLI_
31405
33135
  });
31406
33136
  }
31407
33137
  if (name === 'browser_interact' &&
31408
- isRecord$1(result) &&
31409
- isRecord$1(result.failure) &&
31410
- isRecord$1(result.failure.screenshot) &&
33138
+ isRecord$2(result) &&
33139
+ isRecord$2(result.failure) &&
33140
+ isRecord$2(result.failure.screenshot) &&
31411
33141
  typeof result.failure.screenshot.imageData === 'string') {
31412
33142
  const screenshot = result.failure.screenshot;
31413
33143
  const mimeType = typeof screenshot.mimeType === 'string'
@@ -31616,14 +33346,63 @@ async function handleReferenceInspect(options, context) {
31616
33346
  result: result.data ?? null,
31617
33347
  });
31618
33348
  }
31619
- async function handleReferenceQuery(subcommand, options, context) {
33349
+ /**
33350
+ * The input field a query subcommand fills from its positional text, so
33351
+ * `iwsdk reference search "grab a box"` works without `--input-json`.
33352
+ */
33353
+ const REFERENCE_POSITIONAL_FIELDS = {
33354
+ search: 'query',
33355
+ api: 'name',
33356
+ file: 'file_path',
33357
+ dependents: 'api_name',
33358
+ examples: 'api_name',
33359
+ };
33360
+ /**
33361
+ * Builds the `--input-json` payload for a reference query from the
33362
+ * subcommand's positional text and `--input-json`. Fields given in
33363
+ * `--input-json` win. Returns an error message when the input can't be used.
33364
+ */
33365
+ function buildReferenceQueryInput(subcommand, positional, inputJson) {
33366
+ const text = positional.trim();
33367
+ if (text.length === 0) {
33368
+ return typeof inputJson === 'string' ? { input: inputJson } : {};
33369
+ }
33370
+ const field = REFERENCE_POSITIONAL_FIELDS[subcommand];
33371
+ if (!field) {
33372
+ return {
33373
+ error: `iwsdk reference ${subcommand} takes no positional argument; pass its input with --input-json.`,
33374
+ };
33375
+ }
33376
+ let input = {};
33377
+ if (typeof inputJson === 'string') {
33378
+ try {
33379
+ const parsed = JSON.parse(inputJson);
33380
+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
33381
+ input = parsed;
33382
+ }
33383
+ }
33384
+ catch (error) {
33385
+ return { error: `--input-json must be valid JSON: ${String(error)}` };
33386
+ }
33387
+ }
33388
+ const merged = { [field]: text, ...input };
33389
+ if (subcommand === 'file' && merged.source === undefined) {
33390
+ merged.source = 'iwsdk';
33391
+ }
33392
+ return { input: JSON.stringify(merged) };
33393
+ }
33394
+ async function handleReferenceQuery(subcommand, options, context, positional = '') {
31620
33395
  const workspaceRoot = await resolveReferenceWorkspaceRoot(options, context);
31621
33396
  if (!hasReferenceInstalled(workspaceRoot)) {
31622
33397
  return createFailure('@iwsdk/reference is not installed. Run: pnpm add -D @iwsdk/reference', 'not_installed');
31623
33398
  }
33399
+ const query = buildReferenceQueryInput(subcommand, positional, options.inputJson);
33400
+ if (query.error) {
33401
+ return createFailure(query.error, 'invalid_reference_input');
33402
+ }
31624
33403
  const args = ['--cli-operation', subcommand];
31625
- if (typeof options.inputJson === 'string') {
31626
- args.push('--input-json', options.inputJson);
33404
+ if (query.input !== undefined) {
33405
+ args.push('--input-json', query.input);
31627
33406
  }
31628
33407
  const result = await runReferenceCommand(getReferenceEntrypoint(workspaceRoot), args, workspaceRoot, context, false);
31629
33408
  if (!result.ok) {
@@ -31679,6 +33458,11 @@ const DIRECT_OPTION_ALIASES = {
31679
33458
  browser_set_muted: {
31680
33459
  muted: { parameter: 'muted', type: 'boolean' },
31681
33460
  },
33461
+ browser_filmstrip: {
33462
+ count: { parameter: 'count', type: 'number' },
33463
+ every: { parameter: 'every', type: 'number' },
33464
+ format: { parameter: 'format', type: 'string' },
33465
+ },
31682
33466
  ecs_step: {
31683
33467
  count: { parameter: 'count', type: 'number' },
31684
33468
  frames: { parameter: 'count', type: 'number' },
@@ -31715,6 +33499,7 @@ function resolveRuntimeParams(operationName, options) {
31715
33499
  const aliases = DIRECT_OPTION_ALIASES[operationName] ?? {};
31716
33500
  const allowed = new Set([...COMMON_RUNTIME_OPTIONS, ...Object.keys(aliases)]);
31717
33501
  if (operationName === 'browser_screenshot' ||
33502
+ operationName === 'browser_filmstrip' ||
31718
33503
  operationName === 'scene_screenshot' ||
31719
33504
  operationName === 'scene_render_file' ||
31720
33505
  operationName === 'asset_render_preview' ||
@@ -31738,14 +33523,14 @@ function resolveRuntimeParams(operationName, options) {
31738
33523
  parseDirectValue(options[name], name, alias.type),
31739
33524
  ]));
31740
33525
  }
31741
- function isRecord(value) {
33526
+ function isRecord$1(value) {
31742
33527
  return typeof value === 'object' && value !== null && !Array.isArray(value);
31743
33528
  }
31744
33529
  function withBrowserStatus(result, session) {
31745
33530
  const browser = session.browser ?? null;
31746
33531
  const browserConnected = Boolean(session.browser?.connected);
31747
33532
  const browserCommandReady = isRuntimeBrowserCommandReady(session);
31748
- if (isRecord(result)) {
33533
+ if (isRecord$1(result)) {
31749
33534
  return {
31750
33535
  ...result,
31751
33536
  browser,
@@ -31761,7 +33546,7 @@ function withBrowserStatus(result, session) {
31761
33546
  };
31762
33547
  }
31763
33548
  async function normalizeInteractionFailureScreenshot(result) {
31764
- if (!isRecord(result) || !isRecord(result.failure)) {
33549
+ if (!isRecord$1(result) || !isRecord$1(result.failure)) {
31765
33550
  return result;
31766
33551
  }
31767
33552
  const screenshot = result.failure.screenshot;
@@ -31851,6 +33636,7 @@ async function runRuntimeOperation(operation, options, io, telemetry) {
31851
33636
  result = await normalizeInteractionFailureScreenshot(result);
31852
33637
  }
31853
33638
  const isScreenshotOperation = operation.mcpName === 'browser_screenshot' ||
33639
+ operation.mcpName === 'browser_filmstrip' ||
31854
33640
  operation.mcpName === 'scene_screenshot' ||
31855
33641
  operation.mcpName === 'scene_render_file' ||
31856
33642
  operation.mcpName === 'asset_render_preview' ||
@@ -31883,6 +33669,398 @@ async function runRuntimeOperation(operation, options, io, telemetry) {
31883
33669
  });
31884
33670
  }
31885
33671
 
33672
+ /**
33673
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
33674
+ *
33675
+ * This source code is licensed under the MIT license found in the
33676
+ * LICENSE file in the root directory of this source tree.
33677
+ */
33678
+ const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies'];
33679
+ /** Packages published together (the fixed group in .changeset/config.json, minus private @iwsdk/reference-assets). */
33680
+ const RELEASED_PACKAGES = [
33681
+ '@iwsdk/cli',
33682
+ '@iwsdk/core',
33683
+ '@iwsdk/create',
33684
+ '@iwsdk/locomotor',
33685
+ '@iwsdk/reference',
33686
+ '@iwsdk/scene-composition',
33687
+ '@iwsdk/vite-plugin-dev',
33688
+ '@iwsdk/xr-input',
33689
+ ];
33690
+ function isRecord(value) {
33691
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
33692
+ }
33693
+ /** Indent and line ending of a JSON file, so it is written back the same way. */
33694
+ function formatJson(value, raw) {
33695
+ const indent = raw.match(/^[{[]\r?\n([ \t]+)\S/u)?.[1] ?? ' ';
33696
+ const eol = raw.includes('\r\n') ? '\r\n' : '\n';
33697
+ const final = /\r?\n$/u.test(raw) ? eol : '';
33698
+ return `${JSON.stringify(value, null, indent).replace(/\n/gu, eol)}${final}`;
33699
+ }
33700
+ function declaredVersion(packageJson, name) {
33701
+ for (const field of DEPENDENCY_FIELDS) {
33702
+ const dependencies = packageJson[field];
33703
+ if (isRecord(dependencies) && typeof dependencies[name] === 'string') {
33704
+ const range = semver$1.validRange(dependencies[name]);
33705
+ return range ? (semver$1.minVersion(range)?.version ?? null) : null;
33706
+ }
33707
+ }
33708
+ return null;
33709
+ }
33710
+ /** The new spec in the developer's style: ^ and ~ ranges stay ranges. */
33711
+ function bumpedSpec(current, to) {
33712
+ const operator = current.trim().match(/^[\^~]/u)?.[0] ?? '';
33713
+ return `${operator}${to}`;
33714
+ }
33715
+ /**
33716
+ * Install with the project's package manager. Output streams to stderr so
33717
+ * stdout stays a single JSON result.
33718
+ */
33719
+ function runInstall(packageManager, projectRoot) {
33720
+ const result = spawnSync(packageManager, ['install'], {
33721
+ cwd: projectRoot,
33722
+ stdio: ['ignore', 2, 2],
33723
+ shell: process.platform === 'win32',
33724
+ });
33725
+ if (result.error) {
33726
+ throw new Error(`${packageManager} could not start (${result.error.message}). Install ${packageManager} or enable it with Corepack.`);
33727
+ }
33728
+ if (result.status !== 0) {
33729
+ throw new Error(`${packageManager} install failed (exit ${result.status ?? result.signal}).`);
33730
+ }
33731
+ }
33732
+ /**
33733
+ * Align the app's Three.js alias with the one the installed core uses,
33734
+ * wherever the package manager reads it, and the app's `@types/three` with
33735
+ * core's, so the app type-checks against one Three.js. Returns what changed
33736
+ * and what the developer has to change by hand.
33737
+ */
33738
+ async function alignThree(projectRoot, packageJson, packageManagerRoot) {
33739
+ const corePackageJson = resolveInstalledCorePackageJson(projectRoot);
33740
+ const coreDependencies = corePackageJson
33741
+ ? JSON.parse(readFileSync(corePackageJson, 'utf8')).dependencies
33742
+ : undefined;
33743
+ const coreThree = coreDependencies?.three;
33744
+ if (!coreThree) {
33745
+ return { bumps: [], manualSteps: [] };
33746
+ }
33747
+ const coreThreeTypes = coreDependencies?.['@types/three'];
33748
+ const bumps = [];
33749
+ const manualSteps = [];
33750
+ const setThree = (record, field) => {
33751
+ if (typeof record.three === 'string' && record.three !== coreThree) {
33752
+ bumps.push({ field, name: 'three', from: record.three, to: coreThree });
33753
+ record.three = coreThree;
33754
+ }
33755
+ };
33756
+ // Only where the app already declares it: a mismatched copy makes tsc see
33757
+ // two Three.js type trees (core resolves its own).
33758
+ const setThreeTypes = (record, field) => {
33759
+ const current = record['@types/three'];
33760
+ if (coreThreeTypes &&
33761
+ typeof current === 'string' &&
33762
+ current !== coreThreeTypes) {
33763
+ bumps.push({
33764
+ field,
33765
+ name: '@types/three',
33766
+ from: current,
33767
+ to: coreThreeTypes,
33768
+ });
33769
+ record['@types/three'] = coreThreeTypes;
33770
+ }
33771
+ };
33772
+ for (const field of [
33773
+ ...DEPENDENCY_FIELDS,
33774
+ 'overrides',
33775
+ 'resolutions',
33776
+ ]) {
33777
+ if (isRecord(packageJson[field])) {
33778
+ setThree(packageJson[field], field);
33779
+ setThreeTypes(packageJson[field], field);
33780
+ }
33781
+ }
33782
+ if (isRecord(packageJson.pnpm) && isRecord(packageJson.pnpm.overrides)) {
33783
+ setThree(packageJson.pnpm.overrides, 'pnpm.overrides');
33784
+ }
33785
+ const workspaceFile = path.join(packageManagerRoot, 'pnpm-workspace.yaml');
33786
+ if (existsSync(workspaceFile)) {
33787
+ const text = await readFile(workspaceFile, 'utf8');
33788
+ const match = text.match(/^overrides:\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+three:[ \t]*(\S+)[ \t]*$/mu);
33789
+ const current = match?.[1]?.replace(/^['"]|['"]$/gu, '');
33790
+ if (match && current && current !== coreThree) {
33791
+ if (path.resolve(packageManagerRoot) === path.resolve(projectRoot)) {
33792
+ await writeFile(workspaceFile, text.replace(match[0], match[0].replace(/three:[ \t]*\S+/u, `three: ${coreThree}`)));
33793
+ bumps.push({
33794
+ field: 'pnpm-workspace.yaml overrides',
33795
+ name: 'three',
33796
+ from: current,
33797
+ to: coreThree,
33798
+ });
33799
+ }
33800
+ else {
33801
+ manualSteps.push(`${path.relative(projectRoot, workspaceFile)} overrides three to ${current}; IWSDK now needs ${coreThree}. Change it once every package in the workspace can move.`);
33802
+ }
33803
+ }
33804
+ }
33805
+ return { bumps, manualSteps };
33806
+ }
33807
+ /**
33808
+ * Validate iwsdk.config.json with the validator of the @iwsdk/core now
33809
+ * installed, so settings the new release renamed or removed show up here
33810
+ * instead of as a dev-server error. Null when it could not be checked.
33811
+ */
33812
+ async function validateProjectConfig(projectRoot) {
33813
+ const configPath = path.join(projectRoot, 'iwsdk.config.json');
33814
+ if (!existsSync(configPath)) {
33815
+ return [];
33816
+ }
33817
+ try {
33818
+ const config = JSON.parse(await readFile(configPath, 'utf8'));
33819
+ const corePackageJson = resolveInstalledCorePackageJson(projectRoot);
33820
+ const projectEntry = corePackageJson
33821
+ ? JSON.parse(readFileSync(corePackageJson, 'utf8')).exports?.['./project']?.import
33822
+ : undefined;
33823
+ if (!corePackageJson || !projectEntry) {
33824
+ return null;
33825
+ }
33826
+ const projectModule = (await import(pathToFileURL(path.join(path.dirname(corePackageJson), projectEntry)).href));
33827
+ if (!projectModule.validateIwsdkProjectManifest) {
33828
+ return null;
33829
+ }
33830
+ return projectModule
33831
+ .validateIwsdkProjectManifest(config)
33832
+ .issues.map(({ path: issuePath, message }) => ({
33833
+ path: issuePath,
33834
+ message,
33835
+ }));
33836
+ }
33837
+ catch {
33838
+ return null;
33839
+ }
33840
+ }
33841
+ async function handleUpgrade(options, io) {
33842
+ let projectRoot;
33843
+ if (typeof options.workspace === 'string') {
33844
+ projectRoot = path.resolve(io.cwd, options.workspace);
33845
+ if (!existsSync(path.join(projectRoot, 'package.json'))) {
33846
+ throw new Error(`--workspace ${options.workspace} has no package.json.`);
33847
+ }
33848
+ }
33849
+ else {
33850
+ projectRoot = findGuidanceProjectRoot(io.cwd);
33851
+ }
33852
+ if (projectRoot == null) {
33853
+ throw new Error(`No package.json found at or above ${io.cwd}.`);
33854
+ }
33855
+ const root = projectRoot;
33856
+ const packageJsonPath = path.join(root, 'package.json');
33857
+ const rawPackageJson = await readFile(packageJsonPath, 'utf8');
33858
+ const packageJson = JSON.parse(rawPackageJson);
33859
+ if (!isRecord(packageJson)) {
33860
+ throw new Error('package.json must contain a JSON object.');
33861
+ }
33862
+ const to = typeof options.to === 'string' ? options.to : CLI_VERSION;
33863
+ if (semver$1.valid(to) == null) {
33864
+ throw new Error(`--to must be an exact IWSDK version, got "${to}".`);
33865
+ }
33866
+ const packages = [];
33867
+ const keptSpecs = [];
33868
+ const outsideRelease = [];
33869
+ let declaresIwsdk = false;
33870
+ for (const field of DEPENDENCY_FIELDS) {
33871
+ const dependencies = packageJson[field];
33872
+ if (!isRecord(dependencies)) {
33873
+ continue;
33874
+ }
33875
+ for (const [name, spec] of Object.entries(dependencies)) {
33876
+ if (!name.startsWith('@iwsdk/') || typeof spec !== 'string') {
33877
+ continue;
33878
+ }
33879
+ declaresIwsdk = true;
33880
+ if (!RELEASED_PACKAGES.includes(name)) {
33881
+ outsideRelease.push(`${name}@${spec}`);
33882
+ }
33883
+ else if (semver$1.validRange(spec) == null) {
33884
+ // workspace:, file:, link:, catalog:, git and npm: aliases.
33885
+ keptSpecs.push(`${name}@${spec}`);
33886
+ }
33887
+ else if (bumpedSpec(spec, to) !== spec) {
33888
+ packages.push({ field, name, from: spec, to: bumpedSpec(spec, to) });
33889
+ }
33890
+ }
33891
+ }
33892
+ if (!declaresIwsdk) {
33893
+ throw new Error(`${packageJsonPath} has no @iwsdk/* dependencies. To add IWSDK to this project, run \`npx @iwsdk/create@latest . --yes --target vr\`.`);
33894
+ }
33895
+ const from = readInstalledCoreVersion(root) ??
33896
+ readLockedCoreVersion(root) ??
33897
+ declaredVersion(packageJson, '@iwsdk/core');
33898
+ if (from != null && semver$1.valid(from) && semver$1.gt(from, to)) {
33899
+ throw new Error(`The project already uses IWSDK ${from}, newer than ${to}. Run the matching CLI: npx @iwsdk/cli@${from} upgrade, or pass --to.`);
33900
+ }
33901
+ const packageManagerInfo = findPackageManager(root);
33902
+ const packageManager = packageManagerInfo.name;
33903
+ const guides = migrationsBetween(from, to);
33904
+ const dryRun = options.dryRun !== undefined &&
33905
+ options.dryRun !== false &&
33906
+ options.dryRun !== 'false';
33907
+ const install = options.install !== false && options.noInstall !== true;
33908
+ const manualSteps = [];
33909
+ if (keptSpecs.length > 0) {
33910
+ manualSteps.push(`Left ${keptSpecs.join(', ')} as declared (not registry versions); point them at IWSDK ${to} yourself.`);
33911
+ }
33912
+ if (outsideRelease.length > 0) {
33913
+ manualSteps.push(`${outsideRelease.join(', ')} ${outsideRelease.length === 1 ? 'is' : 'are'} not part of the IWSDK release and ${outsideRelease.length === 1 ? 'was' : 'were'} left as declared.${guides.length > 0 ? ' If a migration guide lists one as retired, remove it as the guide says.' : ''}`);
33914
+ }
33915
+ if (dryRun) {
33916
+ return createSuccess({
33917
+ projectRoot: root,
33918
+ from,
33919
+ to,
33920
+ dryRun,
33921
+ packageManager,
33922
+ installed: false,
33923
+ packages,
33924
+ migrations: guides.map(({ id, introducedIn }) => ({ id, introducedIn })),
33925
+ releaseNotes: { count: releaseNotesBetween(from, to).length },
33926
+ configIssues: [],
33927
+ guidance: {
33928
+ status: 'pending',
33929
+ message: 'Dry run: nothing was written.',
33930
+ },
33931
+ manualSteps,
33932
+ });
33933
+ }
33934
+ for (const bump of packages) {
33935
+ packageJson[bump.field][bump.name] = bump.to;
33936
+ }
33937
+ if (packages.length > 0) {
33938
+ await writeFile(packageJsonPath, formatJson(packageJson, rawPackageJson));
33939
+ }
33940
+ // Written before installing: an install that fails on a retired package
33941
+ // is exactly when the agent needs the migration guide.
33942
+ const migrations = await materializeMigrations(root, guides);
33943
+ const releaseNotes = await writeReleaseNotes(root, from, to);
33944
+ const migrationNotice = [
33945
+ formatMigrationNotice(from, to, migrations),
33946
+ formatReleaseNotesNotice(from, to, releaseNotes),
33947
+ ]
33948
+ .filter(Boolean)
33949
+ .join('\n');
33950
+ const installOrExplain = () => {
33951
+ io.stderr.write(`[IWSDK] Running ${packageManager} install ...\n`);
33952
+ try {
33953
+ runInstall(packageManager, root);
33954
+ }
33955
+ catch (error) {
33956
+ throw new Error([
33957
+ error instanceof Error ? error.message : String(error),
33958
+ `package.json already lists IWSDK ${to}. Fix the error, run \`${packageManager} install\`${packageManagerInfo.root !== root ? ` (workspace root: ${packageManagerInfo.root})` : ''}, then \`npx @iwsdk/cli@latest agents sync\`.`,
33959
+ migrationNotice,
33960
+ ...manualSteps,
33961
+ ]
33962
+ .filter(Boolean)
33963
+ .join('\n'));
33964
+ }
33965
+ };
33966
+ let guidance;
33967
+ let guidanceResult = null;
33968
+ let configIssues = [];
33969
+ if (install) {
33970
+ installOrExplain();
33971
+ const three = await alignThree(root, packageJson, packageManagerInfo.root);
33972
+ manualSteps.push(...three.manualSteps);
33973
+ if (three.bumps.length > 0) {
33974
+ packages.push(...three.bumps);
33975
+ await writeFile(packageJsonPath, formatJson(packageJson, rawPackageJson));
33976
+ installOrExplain();
33977
+ }
33978
+ try {
33979
+ const source = await resolveProjectGuidance(root);
33980
+ // Refresh the coding tools the project already has guidance for; one
33981
+ // without any is the developer's call.
33982
+ const tools = await installedGuidanceTools(root, source);
33983
+ if (tools.length === 0) {
33984
+ guidance = {
33985
+ status: 'none',
33986
+ message: 'This project has no IWSDK agent guidance; `npx @iwsdk/cli@latest agents sync` adds it.',
33987
+ };
33988
+ }
33989
+ else {
33990
+ guidanceResult = await syncAgentGuidance({
33991
+ projectRoot: root,
33992
+ source,
33993
+ tools,
33994
+ });
33995
+ guidance = {
33996
+ status: 'synced',
33997
+ version: guidanceResult.version,
33998
+ changed: guidanceResult.results
33999
+ .filter((entry) => entry.action !== 'unchanged' && entry.action !== 'skipped')
34000
+ .map((entry) => entry.path),
34001
+ skipped: guidanceResult.skipped.map((entry) => entry.path),
34002
+ };
34003
+ }
34004
+ }
34005
+ catch (error) {
34006
+ if (!(error instanceof GuidanceSourceError)) {
34007
+ throw error;
34008
+ }
34009
+ guidance = { status: 'unavailable', message: error.message };
34010
+ }
34011
+ const issues = await validateProjectConfig(root);
34012
+ if (issues == null) {
34013
+ manualSteps.push(`Could not check iwsdk.config.json against IWSDK ${to}; the dev server reports settings it rejects.`);
34014
+ }
34015
+ else if (issues.length > 0) {
34016
+ configIssues = issues;
34017
+ manualSteps.push(`iwsdk.config.json does not validate against IWSDK ${to}: ${issues
34018
+ .map((issue) => `${issue.path} ${issue.message}`)
34019
+ .join('; ')}. The migration guides and release notes say what replaced each setting.`);
34020
+ }
34021
+ }
34022
+ else {
34023
+ guidance = {
34024
+ status: 'pending',
34025
+ message: `Dependencies were not installed. Run \`${packageManager} install\`, then \`npx @iwsdk/cli@latest agents sync\`.`,
34026
+ };
34027
+ manualSteps.push(guidance.message);
34028
+ }
34029
+ const notice = [
34030
+ `[IWSDK] Upgraded ${from ?? 'IWSDK'} -> ${to}.`,
34031
+ migrationNotice,
34032
+ guidanceResult?.agentNotice ??
34033
+ (guidance.status !== 'synced' ? guidance.message : ''),
34034
+ ...(guidanceResult && guidanceResult.skipped.length > 0
34035
+ ? [
34036
+ `Left edited guidance files alone: ${guidanceResult.skipped.map((entry) => entry.path).join(', ')} (\`npx @iwsdk/cli@latest agents sync --force\` replaces them).`,
34037
+ ]
34038
+ : []),
34039
+ ...manualSteps.filter((step) => guidance.status === 'synced' || step !== guidance.message),
34040
+ ]
34041
+ .filter(Boolean)
34042
+ .join('\n');
34043
+ io.stderr.write(`${notice}\n`);
34044
+ return createSuccess({
34045
+ projectRoot: root,
34046
+ from,
34047
+ to,
34048
+ dryRun,
34049
+ packageManager,
34050
+ installed: install,
34051
+ packages,
34052
+ migrations: migrations.map(({ id, introducedIn, path: guidePath }) => ({
34053
+ id,
34054
+ introducedIn,
34055
+ path: guidePath,
34056
+ })),
34057
+ releaseNotes: releaseNotes ?? { count: 0 },
34058
+ configIssues,
34059
+ guidance,
34060
+ manualSteps,
34061
+ });
34062
+ }
34063
+
31886
34064
  /**
31887
34065
  * Copyright (c) Meta Platforms, Inc. and affiliates.
31888
34066
  *
@@ -31933,6 +34111,7 @@ const RUNTIME_HELP_EXAMPLES = {
31933
34111
  steps: [{ label: 'press', target: 'counter-button', press: {} }],
31934
34112
  },
31935
34113
  xr_set_hand_pose: { device: 'hand-right', poseId: 'point' },
34114
+ browser_filmstrip: { count: 6, every: 5 },
31936
34115
  };
31937
34116
  function schemaExample(schema) {
31938
34117
  if (schema.enum?.length) {
@@ -31967,6 +34146,7 @@ function buildRuntimeCommandHelp(domain, action) {
31967
34146
  return [`Unknown ${domain} command "${action}".`];
31968
34147
  }
31969
34148
  const writesScreenshot = operation.mcpName === 'browser_screenshot' ||
34149
+ operation.mcpName === 'browser_filmstrip' ||
31970
34150
  operation.mcpName === 'scene_screenshot' ||
31971
34151
  operation.mcpName === 'scene_render_file' ||
31972
34152
  operation.mcpName === 'asset_render_preview' ||
@@ -31999,6 +34179,9 @@ function buildRuntimeCommandHelp(domain, action) {
31999
34179
  if (operation.mcpName === 'ecs_step') {
32000
34180
  lines.push(' --frames <count> Alias for input count', ' --count <count> Alias for input count', ' --delta <seconds> Alias for input delta');
32001
34181
  }
34182
+ if (operation.mcpName === 'browser_filmstrip') {
34183
+ lines.push(' --count <frames> Alias for input count', ' --every <frames> Alias for input every', ' --format <png|jpeg> Alias for input format');
34184
+ }
32002
34185
  if (operation.mcpName === 'browser_set_muted') {
32003
34186
  lines.push(' --muted <true|false> Alias for input muted');
32004
34187
  }
@@ -32053,16 +34236,15 @@ function buildReferenceCommandHelp(action) {
32053
34236
  return [
32054
34237
  'Usage: iwsdk reference status',
32055
34238
  '',
32056
- 'Show reference project state plus shared corpus and model cache status.',
34239
+ 'Show whether @iwsdk/reference is installed and its bundled corpus loads.',
32057
34240
  ];
32058
34241
  }
32059
34242
  if (action === 'warmup') {
32060
34243
  return [
32061
34244
  'Usage: iwsdk reference warmup',
32062
34245
  '',
32063
- 'Download and initialize the external reference corpus and model caches.',
32064
- 'The pinned model file URLs are baked into the SDK and must remain reachable unless the shared cache is already pre-warmed.',
32065
- 'Set IWSDK_REFERENCE_ASSETS_BASE_URL when you are hosting the corpus payload yourself, including local/internal SDK bundle deployments that do not ship @iwsdk/reference-assets.',
34246
+ 'Check that the corpus bundled with @iwsdk/reference loads.',
34247
+ 'Kept for compatibility; nothing is downloaded and queries work right after install.',
32066
34248
  ];
32067
34249
  }
32068
34250
  if (action === 'inspect') {
@@ -32077,11 +34259,17 @@ function buildReferenceCommandHelp(action) {
32077
34259
  ];
32078
34260
  }
32079
34261
  if (action) {
34262
+ const field = REFERENCE_POSITIONAL_FIELDS[action];
32080
34263
  return [
32081
- `Usage: iwsdk reference ${action} [--input-json <json>] [--raw]`,
34264
+ field
34265
+ ? `Usage: iwsdk reference ${action} [<${field}>] [--input-json <json>] [--raw]`
34266
+ : `Usage: iwsdk reference ${action} [--input-json <json>] [--raw]`,
32082
34267
  '',
32083
34268
  'Run a reference query using the workspace-installed @iwsdk/reference package.',
32084
34269
  '',
34270
+ ...(field
34271
+ ? [`The positional text sets "${field}"; --input-json fields win.`, '']
34272
+ : []),
32085
34273
  'Options:',
32086
34274
  ' --input-json <json> JSON payload matching the reference tool schema',
32087
34275
  ' --raw Emit the raw query payload',
@@ -32094,14 +34282,14 @@ function buildReferenceCommandHelp(action) {
32094
34282
  ' status',
32095
34283
  ' warmup',
32096
34284
  ' inspect [--tool <name>] [--raw]',
32097
- ' search [--input-json <json>] [--raw]',
34285
+ ' search [<query>] [--input-json <json>] [--raw]',
32098
34286
  ' relationship [--input-json <json>] [--raw]',
32099
- ' api [--input-json <json>] [--raw]',
32100
- ' file [--input-json <json>] [--raw]',
34287
+ ' api [<name>] [--input-json <json>] [--raw]',
34288
+ ' file [<file_path>] [--input-json <json>] [--raw]',
32101
34289
  ' components [--input-json <json>] [--raw]',
32102
34290
  ' systems [--input-json <json>] [--raw]',
32103
- ' dependents [--input-json <json>] [--raw]',
32104
- ' examples [--input-json <json>] [--raw]',
34291
+ ' dependents [<api_name>] [--input-json <json>] [--raw]',
34292
+ ' examples [<api_name>] [--input-json <json>] [--raw]',
32105
34293
  ];
32106
34294
  }
32107
34295
  function buildDevCommandHelp(action) {
@@ -32138,6 +34326,46 @@ function buildDevCommandHelp(action) {
32138
34326
  ' open [--workspace <path>]',
32139
34327
  ];
32140
34328
  }
34329
+ function buildAgentsCommandHelp() {
34330
+ return [
34331
+ 'Usage: iwsdk agents sync|check [--tools claude,codex,...] [--force] [--workspace <path>]',
34332
+ '',
34333
+ 'Installs the coding-agent guidance (AGENTS.md block, skills, rules) that ships',
34334
+ 'with the installed @iwsdk/core, so it always matches the IWSDK release in use.',
34335
+ '',
34336
+ 'Subcommands:',
34337
+ ' sync Install or refresh the guidance. Files IWSDK wrote and nobody edited',
34338
+ ' are replaced, retired IWSDK files are removed, and edited files are',
34339
+ ' reported and left alone.',
34340
+ ' check Report differences without writing; exits 1 when the guidance is not',
34341
+ ' current (for CI).',
34342
+ '',
34343
+ 'Options:',
34344
+ ' --tools <list> claude, cursor, copilot, codex, opencode (default: all)',
34345
+ ' --force also replace edited files and files IWSDK does not own',
34346
+ ' --workspace <path> project directory (default: nearest package.json)',
34347
+ ];
34348
+ }
34349
+ function buildUpgradeCommandHelp() {
34350
+ return [
34351
+ 'Usage: npx @iwsdk/cli@latest upgrade [--to <version>] [--dry-run] [--no-install] [--workspace <path>]',
34352
+ '',
34353
+ 'Upgrades every @iwsdk/* dependency in the release group to this CLI release',
34354
+ "(or --to), keeping ^ and ~ ranges, and installs with the project's package",
34355
+ 'manager (found from the nearest lockfile). Then it aligns the Three.js alias',
34356
+ 'with @iwsdk/core, refreshes the coding-agent guidance the project already has,',
34357
+ 'and checks iwsdk.config.json against the new release. It writes to',
34358
+ '.iwsdk/migrations/ (gitignored) a migration guide for each release boundary',
34359
+ 'crossed and release-notes.md with every change in between. Run it with',
34360
+ '@latest so the newest migration guides and release notes are available.',
34361
+ '',
34362
+ 'Options:',
34363
+ ' --to <version> target IWSDK version (default: this CLI version)',
34364
+ ' --dry-run report the version change, migration guides and release-note count only',
34365
+ ' --no-install update package.json without installing',
34366
+ ' --workspace <path> project directory',
34367
+ ];
34368
+ }
32141
34369
  function usageLines() {
32142
34370
  return [
32143
34371
  'Usage: iwsdk <command> [subcommand] [--help]',
@@ -32148,6 +34376,8 @@ function usageLines() {
32148
34376
  ' runtime status|targets|wait|recover|pair-headset',
32149
34377
  ' dev down|logs|open|status',
32150
34378
  ' adapter sync|status|prune|prompt',
34379
+ ' agents sync|check [--tools <list>] [--force]',
34380
+ ' upgrade [--to <version>] [--dry-run] [--no-install]',
32151
34381
  ' reference status|warmup|inspect|search|relationship|api|file|components|systems|dependents|examples',
32152
34382
  ' mcp stdio|inspect [--tool <mcpName>]',
32153
34383
  ' xr <action>',
@@ -32187,6 +34417,14 @@ async function runCli(argv, io = {}) {
32187
34417
  stdout.write(`${buildMcpInspectHelp().join('\n')}\n`);
32188
34418
  return 0;
32189
34419
  }
34420
+ if (command === 'upgrade') {
34421
+ stdout.write(`${buildUpgradeCommandHelp().join('\n')}\n`);
34422
+ return 0;
34423
+ }
34424
+ if (command === 'agents') {
34425
+ stdout.write(`${buildAgentsCommandHelp().join('\n')}\n`);
34426
+ return 0;
34427
+ }
32190
34428
  if (command === 'reference') {
32191
34429
  stdout.write(`${buildReferenceCommandHelp(subcommand).join('\n')}\n`);
32192
34430
  return 0;
@@ -32254,6 +34492,20 @@ async function runCli(argv, io = {}) {
32254
34492
  throw new Error('Usage: iwsdk adapter sync|status|prune|prompt');
32255
34493
  }
32256
34494
  break;
34495
+ case 'upgrade':
34496
+ result = await handleUpgrade(parsed.options, context);
34497
+ break;
34498
+ case 'agents':
34499
+ if (subcommand === 'sync') {
34500
+ result = await handleAgentsSync(parsed.options, context);
34501
+ }
34502
+ else if (subcommand === 'check') {
34503
+ result = await handleAgentsCheck(parsed.options, context);
34504
+ }
34505
+ else {
34506
+ throw new Error(buildAgentsCommandHelp().join('\n'));
34507
+ }
34508
+ break;
32257
34509
  case 'reference':
32258
34510
  if (subcommand === 'status') {
32259
34511
  result = await handleReferenceStatus(parsed.options, context);
@@ -32265,7 +34517,7 @@ async function runCli(argv, io = {}) {
32265
34517
  result = await handleReferenceInspect(parsed.options, context);
32266
34518
  }
32267
34519
  else if (subcommand) {
32268
- result = await handleReferenceQuery(subcommand, parsed.options, context);
34520
+ result = await handleReferenceQuery(subcommand, parsed.options, context, parsed.positionals.slice(2).join(' '));
32269
34521
  }
32270
34522
  else {
32271
34523
  throw new Error('Usage: iwsdk reference status|warmup|inspect|search|relationship|api|file|components|systems|dependents|examples');
@@ -32326,7 +34578,18 @@ async function runCli(argv, io = {}) {
32326
34578
  ? createFailure(error.message, error.code, {
32327
34579
  owner: error.owner,
32328
34580
  })
32329
- : createFailure(error instanceof Error ? error.message : String(error));
34581
+ : error instanceof GuidanceSourceError
34582
+ ? createFailure(error.message, error.code)
34583
+ : createFailure(error instanceof Error ? error.message : String(error));
34584
+ // Set by `dev up` when the guidance refresh ran before startup threw.
34585
+ const agentGuidance = error
34586
+ ?.agentGuidance;
34587
+ if (agentGuidance) {
34588
+ failure.error.details = {
34589
+ ...(failure.error.details ?? {}),
34590
+ agentGuidance,
34591
+ };
34592
+ }
32330
34593
  writeJson(stderr, failure);
32331
34594
  return 1;
32332
34595
  }