@iwsdk/cli 1.1.0 → 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.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
package/dist/cli.js
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
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
|
|
2379
|
-
|
|
2380
|
-
|
|
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
|
-
|
|
2387
|
-
|
|
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$
|
|
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$
|
|
3530
|
+
return isRecord$8(value) && value.__raw === true;
|
|
2487
3531
|
}
|
|
2488
3532
|
function isCliFailure(value) {
|
|
2489
|
-
return isRecord$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
7117
|
+
const paramsRecord = isRecord$7(params) ? params : null;
|
|
6042
7118
|
const expectedTab = paramsRecord?.expectedTab;
|
|
6043
7119
|
if (expectedTab !== undefined &&
|
|
6044
|
-
(!isRecord$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
7327
|
-
const
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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
|
-
|
|
7446
|
-
|
|
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
|
-
|
|
7450
|
-
|
|
7451
|
-
|
|
7452
|
-
|
|
7453
|
-
|
|
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
|
-
|
|
7456
|
-
|
|
7457
|
-
|
|
7458
|
-
|
|
7459
|
-
|
|
7460
|
-
|
|
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
|
-
|
|
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$
|
|
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$
|
|
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$
|
|
8679
|
+
return (isRecord$5(permission) &&
|
|
7565
8680
|
serverNames.every((name) => permission[`${name}_*`] === 'allow') &&
|
|
7566
|
-
isRecord$
|
|
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$
|
|
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$
|
|
8793
|
+
if (!isRecord$4(parsed)) {
|
|
7679
8794
|
return null;
|
|
7680
8795
|
}
|
|
7681
8796
|
const sectionValue = parsed[target.jsonKey ?? 'mcpServers'];
|
|
7682
|
-
if (!isRecord$
|
|
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
|
|
7758
|
-
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
12458
|
-
isRecord$
|
|
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$
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
12917
|
-
|
|
14513
|
+
const source = await resolveProjectGuidance(projectRoot);
|
|
14514
|
+
if (source.origin !== 'installed-core') {
|
|
14515
|
+
return null;
|
|
12918
14516
|
}
|
|
12919
|
-
|
|
12920
|
-
|
|
12921
|
-
|
|
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
|
-
|
|
12924
|
-
|
|
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
|
-
|
|
13108
|
-
|
|
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
|
-
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
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$
|
|
31409
|
-
isRecord$
|
|
31410
|
-
isRecord$
|
|
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
|
-
|
|
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 (
|
|
31626
|
-
args.push('--input-json',
|
|
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
|
|
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
|
-
'
|
|
32064
|
-
'
|
|
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
|
-
|
|
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
|
-
:
|
|
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
|
}
|