@iwsdk/create 1.2.0-rc.0 → 1.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/README.md +21 -6
  2. package/dist/cli.js +470 -90
  3. package/dist/guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
  4. package/dist/guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
  5. package/dist/guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
  6. package/dist/guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  7. package/dist/guidance/files/.agents/skills/iwsdk-dev/SKILL.md +1 -1
  8. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
  9. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  10. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
  11. package/dist/guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
  12. package/dist/guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
  13. package/dist/guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
  14. package/dist/guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  15. package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  16. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  17. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  18. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  19. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  20. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  21. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  22. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  23. package/dist/guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  24. package/dist/guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  25. package/dist/guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
  26. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
  27. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  28. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  29. package/dist/guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  30. package/dist/guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
  31. package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  32. package/dist/guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  33. package/dist/guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  34. package/dist/guidance/files/.claude/rules/ecs-api.md +1 -1
  35. package/dist/guidance/files/.claude/rules/scene-json.md +1 -1
  36. package/dist/guidance/files/.claude/rules/uikitml.md +1 -1
  37. package/dist/guidance/files/.claude/settings.json +1 -0
  38. package/dist/guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  39. package/dist/guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  40. package/dist/guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  41. package/dist/guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  42. package/dist/guidance/files/.claude/skills/iwsdk-dev/SKILL.md +1 -1
  43. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
  44. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  45. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
  46. package/dist/guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  47. package/dist/guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  48. package/dist/guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
  49. package/dist/guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  50. package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  51. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  52. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  53. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  54. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  55. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  56. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  57. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  58. package/dist/guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  59. package/dist/guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  60. package/dist/guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
  61. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
  62. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  63. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  64. package/dist/guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  65. package/dist/guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
  66. package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  67. package/dist/guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  68. package/dist/guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  69. package/dist/guidance/files/.cursor/rules/scene-json.mdc +1 -1
  70. package/dist/guidance/files/.cursor/rules/uikitml.mdc +1 -1
  71. package/dist/guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  72. package/dist/guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  73. package/dist/guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  74. package/dist/guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  75. package/dist/guidance/files/AGENTS.md +1 -1
  76. package/dist/guidance/files/public/scenes/AGENTS.md +1 -1
  77. package/dist/guidance/files/public/ui/AGENTS.md +1 -1
  78. package/dist/guidance/files/src/AGENTS.md +1 -1
  79. package/dist/guidance/manifest.json +111 -11
  80. package/package.json +4 -4
package/dist/cli.js CHANGED
@@ -8,7 +8,7 @@ import require$$1 from 'node:child_process';
8
8
  import path$4 from 'node:path';
9
9
  import require$$3, { existsSync as existsSync$1 } from 'node:fs';
10
10
  import process$3 from 'node:process';
11
- import fsp, { readdir, readFile, lstat, rm, mkdir, writeFile, rename, realpath, rmdir } from 'fs/promises';
11
+ import fsp, { readdir, readFile, lstat, realpath, rm, mkdir, writeFile, rename, rmdir } from 'fs/promises';
12
12
  import { createHash, randomUUID } from 'crypto';
13
13
  import 'module';
14
14
  import { readFile as readFile$1, readdir as readdir$1 } from 'node:fs/promises';
@@ -12604,6 +12604,8 @@ const GUIDANCE_TOOLS = [
12604
12604
  // test/agent-guidance.test.ts checks both sides against a fresh render.
12605
12605
  const GUIDANCE_FORMAT = 1;
12606
12606
  const BLOCK_NAME = 'iwsdk-agent-guidance';
12607
+ /** The root AGENTS.md block unit, which a CLAUDE.md import points at. */
12608
+ const ROOT_BLOCK = 'AGENTS.md';
12607
12609
  const STAMP_LINE = /^<!-- iwsdk-agent-guidance version=(\S+) sha256=([0-9a-f]{64})(?: name=(\S+))? [^\n]*-->\r?\n?/mu;
12608
12610
  const BLOCK_PATTERN = new RegExp(`<!-- BEGIN ${BLOCK_NAME} version=(\\S+) sha256=([0-9a-f]{64}) -->\\n([\\s\\S]*?)<!-- END ${BLOCK_NAME} -->\\n?`, 'u');
12609
12611
  const BLOCK_BEGIN = new RegExp(`<!-- BEGIN ${BLOCK_NAME}\\b`, 'gu');
@@ -12715,6 +12717,12 @@ async function loadGuidanceSource(root, origin = 'explicit') {
12715
12717
  assertRelativeUnitPath(file);
12716
12718
  }
12717
12719
  }
12720
+ for (const [retired, successors] of Object.entries(manifest.successors ?? {})) {
12721
+ assertRelativeUnitPath(retired);
12722
+ for (const successor of successors) {
12723
+ assertRelativeUnitPath(successor);
12724
+ }
12725
+ }
12718
12726
  return { root, manifest, origin };
12719
12727
  }
12720
12728
  function selectedUnits(manifest, tools) {
@@ -12739,11 +12747,14 @@ async function isSameFile(first, second) {
12739
12747
  return false;
12740
12748
  }
12741
12749
  }
12742
- /** Temporary siblings a sync left behind when it was killed mid-swap. */
12743
- const TEMPORARY_SIBLING = /^\..+\.iwsdk-(?:new|old)-(\d+)-(\d+)$/u;
12750
+ /**
12751
+ * Temporary siblings a sync left behind when it was killed mid-swap: the
12752
+ * name they stand in for, `new` or `old`, the process id and the time.
12753
+ */
12754
+ const TEMPORARY_SIBLING = /^\.(.+)\.iwsdk-(new|old)-(\d+)-(\d+)$/u;
12744
12755
  /** A temporary sibling that a sync running right now may still need. */
12745
12756
  function isInUse(name) {
12746
- const [, pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
12757
+ const [, , , pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
12747
12758
  if (Date.now() - Number(createdAt) < 10 * 60_000) {
12748
12759
  return true;
12749
12760
  }
@@ -12900,6 +12911,19 @@ function replacementResult(unit, ownership, force) {
12900
12911
  }
12901
12912
  return null;
12902
12913
  }
12914
+ /**
12915
+ * A unit that `onlyExisting` left out because the project does not have it.
12916
+ * `lacks` names what an existing file is missing.
12917
+ */
12918
+ function missingResult(unit, unitPath = unit.path, lacks) {
12919
+ return {
12920
+ path: unitPath,
12921
+ kind: unit.kind,
12922
+ action: 'skipped',
12923
+ reason: 'missing',
12924
+ ...(lacks ? { detail: lacks } : {}),
12925
+ };
12926
+ }
12903
12927
  async function pathKind(filePath) {
12904
12928
  try {
12905
12929
  const stat = await lstat(filePath);
@@ -12912,7 +12936,13 @@ async function pathKind(filePath) {
12912
12936
  throw error;
12913
12937
  }
12914
12938
  }
12915
- async function syncDirectoryUnit(unit, source, writer, force) {
12939
+ /**
12940
+ * The unit syncs below take `create`: whether a unit the project lacks (a
12941
+ * missing file or folder, or a block or import missing from a file) may be
12942
+ * written. `onlyExisting` allows it only for units that replace guidance
12943
+ * this run retires, and for folders a killed sync was replacing.
12944
+ */
12945
+ async function syncDirectoryUnit(unit, source, writer, force, create) {
12916
12946
  const localRoot = path$5.join(writer.projectRoot, unit.path);
12917
12947
  const replace = async () => {
12918
12948
  const files = [];
@@ -12924,6 +12954,9 @@ async function syncDirectoryUnit(unit, source, writer, force) {
12924
12954
  const kind = await pathKind(localRoot);
12925
12955
  const localFiles = kind === 'directory' ? await readTree(localRoot) : null;
12926
12956
  if (kind === 'missing' || localFiles?.size === 0) {
12957
+ if (!create) {
12958
+ return missingResult(unit);
12959
+ }
12927
12960
  await replace();
12928
12961
  return { path: unit.path, kind: unit.kind, action: 'created' };
12929
12962
  }
@@ -12957,10 +12990,13 @@ async function syncDirectoryUnit(unit, source, writer, force) {
12957
12990
  }
12958
12991
  return result;
12959
12992
  }
12960
- async function syncFileUnit(unit, source, writer, force) {
12993
+ async function syncFileUnit(unit, source, writer, force, create) {
12961
12994
  const local = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
12962
12995
  const next = await readSourceFile(source, unit.path);
12963
12996
  if (local == null) {
12997
+ if (!create) {
12998
+ return missingResult(unit);
12999
+ }
12964
13000
  await writer.write(unit.path, next);
12965
13001
  return { path: unit.path, kind: unit.kind, action: 'created' };
12966
13002
  }
@@ -12974,10 +13010,13 @@ async function syncFileUnit(unit, source, writer, force) {
12974
13010
  }
12975
13011
  return result;
12976
13012
  }
12977
- async function syncBlockUnit(unit, source, writer, force) {
13013
+ async function syncBlockUnit(unit, source, writer, force, create) {
12978
13014
  const local = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
12979
13015
  const block = (await readSourceFile(source, unit.path)).toString('utf8');
12980
13016
  if (local == null) {
13017
+ if (!create) {
13018
+ return missingResult(unit);
13019
+ }
12981
13020
  await writer.write(unit.path, block);
12982
13021
  return { path: unit.path, kind: unit.kind, action: 'created' };
12983
13022
  }
@@ -13036,6 +13075,10 @@ async function syncBlockUnit(unit, source, writer, force) {
13036
13075
  reason: 'forced',
13037
13076
  };
13038
13077
  }
13078
+ if (!create) {
13079
+ // No IWSDK block: the developer removed it or replaced the file.
13080
+ return missingResult(unit, unit.path, 'no iwsdk-agent-guidance block');
13081
+ }
13039
13082
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(normalized)}${normalized.trim() ? '\n' : ''}${block}`, local));
13040
13083
  return {
13041
13084
  path: unit.path,
@@ -13044,23 +13087,54 @@ async function syncBlockUnit(unit, source, writer, force) {
13044
13087
  reason: 'appended',
13045
13088
  };
13046
13089
  }
13047
- async function syncClaudeImport(unit, source, writer, force) {
13090
+ /**
13091
+ * A root CLAUDE.md that holds the full guidance of a release before 1.0, as
13092
+ * that release wrote it. It is replaced with an `@AGENTS.md` import, so the
13093
+ * guidance it held now comes from the AGENTS.md block.
13094
+ */
13095
+ async function holdsLegacyClaudeGuidance(unit, source, projectRoot) {
13096
+ const filePath = path$5.join(projectRoot, unit.path);
13097
+ const rootFile = await readTextIfExists(filePath);
13098
+ if (rootFile == null ||
13099
+ (await isSameFile(filePath, path$5.join(projectRoot, ROOT_BLOCK)))) {
13100
+ return false;
13101
+ }
13102
+ const hash = fileUnitHash(rootFile);
13103
+ return (hash !==
13104
+ fileUnitHash((await readSourceFile(source, unit.path)).toString()) &&
13105
+ (source.manifest.legacy[unit.path]?.includes(hash) ?? false));
13106
+ }
13107
+ /**
13108
+ * `replaceLegacy`: whether a CLAUDE.md holding the full guidance of a release
13109
+ * before 1.0 may become an import, which needs the AGENTS.md block in place.
13110
+ */
13111
+ async function syncClaudeImport(unit, source, writer, force, create, replaceLegacy) {
13048
13112
  const rootFile = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
13049
13113
  const nestedFile = await readTextIfExists(path$5.join(writer.projectRoot, '.claude', 'CLAUDE.md'));
13050
13114
  const next = await readSourceFile(source, unit.path);
13051
13115
  if (rootFile == null && nestedFile == null) {
13116
+ if (!create) {
13117
+ return missingResult(unit);
13118
+ }
13052
13119
  await writer.write(unit.path, next);
13053
13120
  return { path: unit.path, kind: unit.kind, action: 'created' };
13054
13121
  }
13055
13122
  if (rootFile != null &&
13056
- (await isSameFile(path$5.join(writer.projectRoot, unit.path), path$5.join(writer.projectRoot, 'AGENTS.md')))) {
13123
+ (await isSameFile(path$5.join(writer.projectRoot, unit.path), path$5.join(writer.projectRoot, ROOT_BLOCK)))) {
13057
13124
  // CLAUDE.md is a link to AGENTS.md: Claude already reads the guidance.
13058
13125
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
13059
13126
  }
13060
- if (rootFile != null &&
13061
- fileUnitHash(rootFile) !== fileUnitHash(next.toString('utf8')) &&
13062
- source.manifest.legacy[unit.path]?.includes(fileUnitHash(rootFile))) {
13127
+ if (await holdsLegacyClaudeGuidance(unit, source, writer.projectRoot)) {
13063
13128
  // Releases before 1.0 put the full guidance in CLAUDE.md.
13129
+ if (!replaceLegacy) {
13130
+ return {
13131
+ path: unit.path,
13132
+ kind: unit.kind,
13133
+ action: 'skipped',
13134
+ reason: 'retired',
13135
+ detail: 'It holds the full guidance of an IWSDK release before 1.0, and becomes an @AGENTS.md import once AGENTS.md has the iwsdk-agent-guidance block.',
13136
+ };
13137
+ }
13064
13138
  await writer.write(unit.path, withLineEndings(next.toString('utf8'), rootFile));
13065
13139
  return {
13066
13140
  path: unit.path,
@@ -13093,6 +13167,10 @@ async function syncClaudeImport(unit, source, writer, force) {
13093
13167
  (nestedFile != null && /^@\.\.\/AGENTS\.md\s*$/mu.test(nestedFile))) {
13094
13168
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
13095
13169
  }
13170
+ if (!create) {
13171
+ // The import was removed, or CLAUDE.md replaced.
13172
+ return missingResult(unit, rootFile != null ? unit.path : '.claude/CLAUDE.md', 'no @AGENTS.md import');
13173
+ }
13096
13174
  if (rootFile != null) {
13097
13175
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(rootFile)}\n@AGENTS.md\n`, rootFile));
13098
13176
  return {
@@ -13126,9 +13204,12 @@ function ownedSkillNames(manifest) {
13126
13204
  }
13127
13205
  return names;
13128
13206
  }
13129
- async function syncClaudeSettings(unit, source, writer, installedSkills, retiredSkills, force) {
13207
+ async function syncClaudeSettings(unit, source, writer, skills, force, onlyExisting, create) {
13130
13208
  const filePath = path$5.join(writer.projectRoot, unit.path);
13131
13209
  const raw = await readTextIfExists(filePath);
13210
+ if (raw == null && !create) {
13211
+ return missingResult(unit);
13212
+ }
13132
13213
  let settings = {};
13133
13214
  if (raw != null) {
13134
13215
  let parsed;
@@ -13160,24 +13241,34 @@ async function syncClaudeSettings(unit, source, writer, installedSkills, retired
13160
13241
  const shipped = new Set(unit.skills ?? []);
13161
13242
  const owned = new Set([
13162
13243
  ...ownedSkillNames(source.manifest),
13163
- ...retiredSkills,
13244
+ ...skills.removed,
13164
13245
  ]);
13246
+ const skillOf = (rule) => typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
13247
+ const allowed = new Set(allow.map(skillOf));
13165
13248
  // Grant skills this sync installed (all of them for a new settings file);
13166
13249
  // a permission the developer removed for an untouched skill stays removed.
13167
13250
  // Grant every shipped skill when the file is new, when --force is given, or
13168
13251
  // when no IWSDK skill permission is left (after `adapter prune`, say).
13252
+ // `onlyExisting` grants a skill only the permission of the retired skill it
13253
+ // replaces, and keeps the permissions of retired skills that stay.
13169
13254
  const grantAll = raw == null ||
13170
13255
  force ||
13171
13256
  !allow.some((rule) => {
13172
- const name = typeof rule === 'string'
13173
- ? rule.match(SKILL_PERMISSION)?.[1]
13174
- : undefined;
13257
+ const name = skillOf(rule);
13175
13258
  return name != null && owned.has(name);
13176
13259
  });
13177
- const grant = [...shipped].filter((name) => grantAll || installedSkills.has(name));
13260
+ const grant = onlyExisting && raw != null
13261
+ ? [...skills.replacedBy]
13262
+ .filter(([retired]) => allowed.has(retired))
13263
+ .flatMap(([, successors]) => successors)
13264
+ .filter((name) => shipped.has(name))
13265
+ : [...shipped].filter((name) => grantAll || skills.installed.has(name));
13178
13266
  const isRetired = (rule) => {
13179
- const name = typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
13180
- return name != null && owned.has(name) && !shipped.has(name);
13267
+ const name = skillOf(rule);
13268
+ return (name != null &&
13269
+ owned.has(name) &&
13270
+ !shipped.has(name) &&
13271
+ !(onlyExisting && skills.kept.has(name)));
13181
13272
  };
13182
13273
  const nextAllow = allow.filter((rule) => !isRetired(rule));
13183
13274
  for (const name of grant) {
@@ -13255,7 +13346,14 @@ function toolsForPath(unitPath) {
13255
13346
  }
13256
13347
  return GUIDANCE_TOOLS;
13257
13348
  }
13258
- async function pruneRetiredUnits(source, tools, writer) {
13349
+ /**
13350
+ * IWSDK units in the project that this release no longer ships, for the
13351
+ * selected tools. Also returns the temporary siblings a killed sync left
13352
+ * behind, for the caller to delete once its writes are done, and the units
13353
+ * such a sync was replacing when it was killed (their folder is gone, so
13354
+ * they count as present).
13355
+ */
13356
+ async function findRetiredUnits(source, tools, writer) {
13259
13357
  const shipped = new Set(source.manifest.units.map((unit) => unit.path));
13260
13358
  const blocks = new Set(source.manifest.units
13261
13359
  .filter((unit) => unit.kind === 'block' || unit.kind === 'claude-import')
@@ -13293,8 +13391,9 @@ async function pruneRetiredUnits(source, tools, writer) {
13293
13391
  }
13294
13392
  }
13295
13393
  }
13296
- const results = [];
13297
- const removedSkills = new Set();
13394
+ const retired = [];
13395
+ const interrupted = new Set();
13396
+ const leftovers = [];
13298
13397
  for (const directory of ['.', ...PRUNE_ROOTS.map((root) => root.directory)]) {
13299
13398
  let entries;
13300
13399
  try {
@@ -13304,7 +13403,15 @@ async function pruneRetiredUnits(source, tools, writer) {
13304
13403
  continue;
13305
13404
  }
13306
13405
  for (const name of entries.filter((entry) => TEMPORARY_SIBLING.test(entry) && !isInUse(entry))) {
13307
- await writer.remove(path$5.posix.join(directory, name));
13406
+ const [, original, label] = TEMPORARY_SIBLING.exec(name);
13407
+ const originalPath = path$5.posix.join(directory, original);
13408
+ if (label === 'old' &&
13409
+ (await pathKind(path$5.join(writer.projectRoot, originalPath))) ===
13410
+ 'missing') {
13411
+ // Killed between the two renames of replaceDirectory.
13412
+ interrupted.add(originalPath);
13413
+ }
13414
+ leftovers.push(path$5.posix.join(directory, name));
13308
13415
  }
13309
13416
  }
13310
13417
  for (const [unitPath, kind] of candidates) {
@@ -13330,24 +13437,13 @@ async function pruneRetiredUnits(source, tools, writer) {
13330
13437
  continue;
13331
13438
  }
13332
13439
  const ownership = classify(localHash, undefined, stamp, source.manifest.legacy[unitPath], source.manifest.version);
13333
- if (ownership === 'managed' || ownership === 'legacy') {
13334
- await writer.remove(unitPath);
13335
- results.push({ path: unitPath, kind, action: 'removed' });
13336
- if (kind === 'directory') {
13337
- removedSkills.add(name);
13338
- }
13339
- }
13340
- else if (ownership === 'modified') {
13341
- // A retired IWSDK unit the developer edited: keep it, but say so.
13342
- results.push({
13343
- path: unitPath,
13344
- kind,
13345
- action: 'skipped',
13346
- reason: 'modified',
13347
- });
13440
+ if (ownership === 'managed' ||
13441
+ ownership === 'legacy' ||
13442
+ ownership === 'modified') {
13443
+ retired.push({ path: unitPath, kind, ownership });
13348
13444
  }
13349
13445
  }
13350
- return { results, removedSkills };
13446
+ return { retired, interrupted, leftovers };
13351
13447
  }
13352
13448
  function readSkillDescription(text) {
13353
13449
  const frontmatter = normalizeText(text).match(/^---\n([\s\S]*?)\n---/u)?.[1];
@@ -13426,44 +13522,153 @@ function buildAgentNotice(source, skills, dryRun, changedCount) {
13426
13522
  /**
13427
13523
  * Write a guidance release into a project. Files IWSDK wrote and nobody edited
13428
13524
  * are replaced; edited files and files IWSDK does not own are reported and left
13429
- * alone unless `force` is set; retired IWSDK files are removed.
13525
+ * alone unless `force` is set; retired IWSDK files are removed once what
13526
+ * replaces them is in place. Missing units are created unless `onlyExisting`
13527
+ * is set (see there).
13430
13528
  */
13431
- async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, }) {
13529
+ async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, onlyExisting = false, }) {
13432
13530
  const writer = createWriter(projectRoot, dryRun);
13433
- const pruned = await pruneRetiredUnits(source, tools, writer);
13531
+ const { retired, interrupted, leftovers } = await findRetiredUnits(source, tools, writer);
13532
+ const units = selectedUnits(source.manifest, tools);
13533
+ const shipped = new Set(source.manifest.units.map((unit) => unit.path));
13534
+ const selected = new Map(units.map((unit) => [unit.path, unit.kind]));
13535
+ // A successor for a coding tool the project does not use is not this
13536
+ // project's, and settings replace no guidance (permissions follow the
13537
+ // skills); one this release does not ship can never be written.
13538
+ const counts = (successor) => shipped.has(successor)
13539
+ ? (selected.get(successor) ?? 'claude-settings') !== 'claude-settings'
13540
+ : true;
13541
+ // Retired units IWSDK wrote and nobody edited are replaced: removed once
13542
+ // the units that replace them are in place. `onlyExisting` replaces only
13543
+ // the ones the release names successors for, and keeps the rest.
13544
+ const replacing = new Map();
13545
+ for (const unit of retired) {
13546
+ const successors = source.manifest.successors?.[unit.path];
13547
+ if (unit.ownership !== 'modified' && (successors || !onlyExisting)) {
13548
+ replacing.set(unit.path, (successors ?? []).filter(counts));
13549
+ }
13550
+ }
13551
+ const claudeImport = units.find((unit) => unit.kind === 'claude-import');
13552
+ const migratesClaude = onlyExisting &&
13553
+ claudeImport != null &&
13554
+ (await holdsLegacyClaudeGuidance(claudeImport, source, projectRoot));
13555
+ // What `onlyExisting` may add: the successors of the guidance this run
13556
+ // replaces, and folders a killed sync was replacing.
13557
+ const additions = new Set([
13558
+ ...[...replacing.values()].flat(),
13559
+ ...(migratesClaude ? [ROOT_BLOCK] : []),
13560
+ ...interrupted,
13561
+ ]);
13562
+ const create = (unit) => !onlyExisting || additions.has(unit.path);
13434
13563
  const results = [];
13564
+ const resultsByUnit = new Map();
13565
+ // In the project once this run is done (in a dry run, once it would be).
13566
+ const present = (unitPath) => {
13567
+ const result = resultsByUnit.get(unitPath);
13568
+ return result !== undefined && result.reason !== 'missing';
13569
+ };
13570
+ // AGENTS.md holds the iwsdk-agent-guidance block once this run is done: not
13571
+ // when it is missing, holds edited guidance from before the block, or has
13572
+ // broken markers.
13573
+ const holdsRootBlock = () => {
13574
+ const reason = resultsByUnit.get(ROOT_BLOCK)?.reason;
13575
+ return (present(ROOT_BLOCK) &&
13576
+ reason !== 'legacy-modified' &&
13577
+ reason !== 'malformed-block');
13578
+ };
13435
13579
  const installedSkills = new Set();
13436
- const units = selectedUnits(source.manifest, tools);
13437
- // Settings last: they grant the skills this run installed.
13438
- for (const unit of [
13439
- ...units.filter((candidate) => candidate.kind !== 'claude-settings'),
13440
- ...units.filter((candidate) => candidate.kind === 'claude-settings'),
13441
- ]) {
13580
+ // The CLAUDE.md import after the AGENTS.md block it points at. Settings
13581
+ // last, once the skills and retired units are settled.
13582
+ const position = (unit) => unit.kind === 'claude-import' ? 1 : unit.kind === 'claude-settings' ? 2 : 0;
13583
+ for (const unit of [...units].sort((left, right) => position(left) - position(right))) {
13584
+ let result;
13442
13585
  switch (unit.kind) {
13443
- case 'directory': {
13444
- const result = await syncDirectoryUnit(unit, source, writer, force);
13586
+ case 'directory':
13587
+ result = await syncDirectoryUnit(unit, source, writer, force, create(unit));
13445
13588
  if (unit.path.startsWith('.claude/') &&
13446
13589
  (result.action === 'created' || result.action === 'updated')) {
13447
13590
  installedSkills.add(path$5.posix.basename(unit.path));
13448
13591
  }
13449
- results.push(result);
13450
13592
  break;
13451
- }
13452
13593
  case 'file':
13453
- results.push(await syncFileUnit(unit, source, writer, force));
13594
+ result = await syncFileUnit(unit, source, writer, force, create(unit));
13454
13595
  break;
13455
13596
  case 'block':
13456
- results.push(await syncBlockUnit(unit, source, writer, force));
13597
+ result = await syncBlockUnit(unit, source, writer, force, create(unit));
13457
13598
  break;
13458
13599
  case 'claude-import':
13459
- results.push(await syncClaudeImport(unit, source, writer, force));
13600
+ result = await syncClaudeImport(unit, source, writer, force, create(unit), !onlyExisting || holdsRootBlock());
13460
13601
  break;
13461
13602
  case 'claude-settings':
13462
- results.push(await syncClaudeSettings(unit, source, writer, installedSkills, pruned.removedSkills, force));
13463
- break;
13603
+ continue;
13604
+ }
13605
+ results.push(result);
13606
+ resultsByUnit.set(unit.path, result);
13607
+ }
13608
+ const removals = [];
13609
+ const retiredResults = [];
13610
+ for (const unit of retired) {
13611
+ const successors = replacing.get(unit.path);
13612
+ const result = { path: unit.path, kind: unit.kind };
13613
+ if (unit.ownership === 'modified') {
13614
+ // A retired IWSDK unit the developer edited: keep it, but say so.
13615
+ retiredResults.push({ ...result, action: 'skipped', reason: 'modified' });
13616
+ }
13617
+ else if (successors == null) {
13618
+ retiredResults.push({
13619
+ ...result,
13620
+ action: 'skipped',
13621
+ reason: 'retired',
13622
+ detail: `IWSDK ${source.manifest.version} no longer ships it and does not name a replacement; \`npx @iwsdk/cli@latest agents sync\` removes it.`,
13623
+ });
13624
+ }
13625
+ else if (!successors.every(present)) {
13626
+ // Never leave a project with less guidance than it had.
13627
+ retiredResults.push({
13628
+ ...result,
13629
+ action: 'skipped',
13630
+ reason: 'retired',
13631
+ detail: `It stays until ${successors.filter((successor) => !present(successor)).join(', ')} can be written in its place.`,
13632
+ });
13633
+ }
13634
+ else {
13635
+ removals.push(unit);
13636
+ retiredResults.push({
13637
+ ...result,
13638
+ action: 'removed',
13639
+ ...(successors.length > 0 ? { replacedBy: successors } : {}),
13640
+ });
13464
13641
  }
13465
13642
  }
13466
- results.push(...pruned.results);
13643
+ const settings = units.find((unit) => unit.kind === 'claude-settings');
13644
+ if (settings) {
13645
+ const claudeSkill = (unitPath) => unitPath.startsWith('.claude/skills/');
13646
+ const name = (unitPath) => path$5.posix.basename(unitPath);
13647
+ results.push(await syncClaudeSettings(settings, source, writer, {
13648
+ installed: installedSkills,
13649
+ removed: new Set(removals
13650
+ .filter((unit) => unit.kind === 'directory')
13651
+ .map((unit) => name(unit.path))),
13652
+ kept: new Set(retired
13653
+ .filter((unit) => claudeSkill(unit.path) && !removals.includes(unit))
13654
+ .map((unit) => name(unit.path))),
13655
+ replacedBy: new Map(removals
13656
+ .filter((unit) => claudeSkill(unit.path))
13657
+ .map((unit) => [
13658
+ name(unit.path),
13659
+ replacing.get(unit.path).filter(claudeSkill).map(name),
13660
+ ])),
13661
+ }, force, onlyExisting, create(settings)));
13662
+ }
13663
+ for (const unit of removals) {
13664
+ await writer.remove(unit.path);
13665
+ }
13666
+ // Last: until a folder that a killed sync moved aside is written again,
13667
+ // its moved-aside copy is what tells the next sync to write it.
13668
+ for (const leftover of leftovers) {
13669
+ await writer.remove(leftover);
13670
+ }
13671
+ results.push(...retiredResults);
13467
13672
  const skills = await summarizeSkills(source, tools);
13468
13673
  const changedCount = results.filter((result) => result.action !== 'unchanged' && result.action !== 'skipped').length;
13469
13674
  return {
@@ -20598,6 +20803,26 @@ function depthAt(code, start, offset) {
20598
20803
  }
20599
20804
  return depth;
20600
20805
  }
20806
+ /**
20807
+ * Whether the config loads @iwsdk/vite-plugin-dev with a static `import`,
20808
+ * `export … from` or `require()`. A config that Vite loads as CommonJS fails
20809
+ * on that, because the package is ESM-only. A dynamic `import()` works in
20810
+ * either, and `import type` is erased before the config runs.
20811
+ */
20812
+ function loadsPluginStatically(source) {
20813
+ const code = blankNonCode(source);
20814
+ const loads = /(?:^|[^\w$.])(?:(?:import|export)(\s+type(?!\s+from\b))?\b[^;'"`]*?\bfrom|import|require\s*\()\s*(['"])/gu;
20815
+ for (const match of code.matchAll(loads)) {
20816
+ // Strings are blanked in `code`; read the specifier from the source.
20817
+ const open = match.index + match[0].length - 1;
20818
+ const specifier = source.slice(open + 1, source.indexOf(match[2], open + 1));
20819
+ if (match[1] == null &&
20820
+ /^@iwsdk\/vite-plugin-dev(?:\/|$)/u.test(specifier)) {
20821
+ return true;
20822
+ }
20823
+ }
20824
+ return false;
20825
+ }
20601
20826
  function patchViteConfig(source) {
20602
20827
  const code = blankNonCode(source);
20603
20828
  if (/@iwsdk\/vite-plugin-dev/u.test(source) && /\biwsdkDev\b/u.test(code)) {
@@ -20673,13 +20898,14 @@ class AdoptError extends Error {
20673
20898
  this.name = 'AdoptError';
20674
20899
  }
20675
20900
  }
20901
+ /** In the order Vite 7 looks for them: it loads the first it finds. */
20676
20902
  const VITE_CONFIG_NAMES = [
20677
- 'vite.config.ts',
20678
- 'vite.config.mts',
20679
20903
  'vite.config.js',
20680
20904
  'vite.config.mjs',
20681
- 'vite.config.cts',
20905
+ 'vite.config.ts',
20682
20906
  'vite.config.cjs',
20907
+ 'vite.config.mts',
20908
+ 'vite.config.cts',
20683
20909
  ];
20684
20910
  /** @iwsdk/vite-plugin-dev's peer range. */
20685
20911
  const VITE_PEER_RANGE = '^7.0.0';
@@ -20704,6 +20930,40 @@ function stringRecord(value) {
20704
20930
  function isRegistrySpec(spec) {
20705
20931
  return semver$4.validRange(spec) != null;
20706
20932
  }
20933
+ /** A dist-tag such as `latest`: the registry picks the version at install. */
20934
+ function isDistTag(spec) {
20935
+ return /^[a-z][\w.-]*$/iu.test(spec) && !isRegistrySpec(spec);
20936
+ }
20937
+ /** A scene keys LocomotionEnvironment with or without the prefix core strips. */
20938
+ const LOCOMOTION_ENVIRONMENT_KEYS = [
20939
+ 'LocomotionEnvironment',
20940
+ 'com.iwsdk.components.LocomotionEnvironment',
20941
+ ];
20942
+ /** Whether any node, prefab or override in a scene has LocomotionEnvironment. */
20943
+ function hasLocomotionEnvironment(value) {
20944
+ if (Array.isArray(value)) {
20945
+ return value.some(hasLocomotionEnvironment);
20946
+ }
20947
+ if (!isRecord$1(value)) {
20948
+ return false;
20949
+ }
20950
+ const { components } = value;
20951
+ return ((isRecord$1(components) &&
20952
+ LOCOMOTION_ENVIRONMENT_KEYS.some((key) => key in components)) ||
20953
+ Object.values(value).some(hasLocomotionEnvironment));
20954
+ }
20955
+ async function readJson(file) {
20956
+ try {
20957
+ return JSON.parse(await fsp.readFile(file, 'utf8'));
20958
+ }
20959
+ catch {
20960
+ return null;
20961
+ }
20962
+ }
20963
+ /** The .mjs or .mts name, which Vite loads as ESM whatever package.json says. */
20964
+ function esmConfigName(name) {
20965
+ return name.replace(/\.c?([jt]s)$/u, '.m$1');
20966
+ }
20707
20967
  /** True when `spec` asks for an older release than `wanted`. */
20708
20968
  function isOlder(spec, wanted) {
20709
20969
  const current = semver$4.minVersion(spec);
@@ -20748,7 +21008,7 @@ export const worldReady = World.create(sceneContainer(), projectOptions);
20748
21008
  * its own folder so it can never shadow the project's modules, plus the
20749
21009
  * starter's project-level files where the project has none.
20750
21010
  */
20751
- function skeletonFiles(files, language) {
21011
+ function skeletonFiles(files, language, esmPackage) {
20752
21012
  const byPath = new Map(files.map((file) => [file.path, file]));
20753
21013
  const extension = language === 'ts' ? 'ts' : 'js';
20754
21014
  const entry = `${SKELETON_DIRECTORY}/index.${extension}`;
@@ -20805,9 +21065,14 @@ function skeletonFiles(files, language) {
20805
21065
  '.codex/config.toml',
20806
21066
  ]) {
20807
21067
  const file = byPath.get(name);
20808
- if (file) {
20809
- skeleton.push(file);
21068
+ if (!file) {
21069
+ continue;
20810
21070
  }
21071
+ // Vite loads vite.config.ts/.js as CommonJS unless package.json says
21072
+ // "type": "module"; .mts/.mjs always load as ESM, which the plugin needs.
21073
+ skeleton.push(name.startsWith('vite.config.') && !esmPackage
21074
+ ? { ...file, path: name.replace(/\.(ts|js)$/u, '.m$1') }
21075
+ : file);
20811
21076
  }
20812
21077
  return skeleton;
20813
21078
  }
@@ -20883,7 +21148,7 @@ workspaceRoot = null) {
20883
21148
  }
20884
21149
  else if (name === 'vite') {
20885
21150
  if (!isRegistrySpec(current)) {
20886
- keep('not a registry version; check it satisfies Vite 7');
21151
+ keep(`${isDistTag(current) ? 'a dist-tag' : 'not a registry version'}; check it satisfies Vite 7`);
20887
21152
  continue;
20888
21153
  }
20889
21154
  if (semver$4.subset(semver$4.validRange(current), VITE_PEER_RANGE)) {
@@ -20894,11 +21159,16 @@ workspaceRoot = null) {
20894
21159
  continue;
20895
21160
  }
20896
21161
  else if (!isRegistrySpec(current)) {
20897
- keep('not a registry version');
21162
+ keep(isDistTag(current)
21163
+ ? 'a dist-tag, not a version range'
21164
+ : 'not a registry version');
20898
21165
  continue;
20899
21166
  }
20900
21167
  else if (!isOlder(current, spec)) {
20901
- keep('newer than this release');
21168
+ // ^1.2.0 for 1.2.0 already asks for this release: nothing to report.
21169
+ if (isOlder(spec, current)) {
21170
+ keep('newer than this release');
21171
+ }
20902
21172
  continue;
20903
21173
  }
20904
21174
  report.changed.push({ field: declaredIn, name, from: current, to: spec });
@@ -21038,7 +21308,7 @@ function mergePnpmOverrides(raw, overrides) {
21038
21308
  }
21039
21309
  return { text: document.toString(), added, replaced };
21040
21310
  }
21041
- async function adoptExistingProject({ outDir, files, guidanceRoot, language, }) {
21311
+ async function adoptExistingProject({ outDir, files, guidanceRoot, language, locomotionOffRequested = false, }) {
21042
21312
  // 1. Check everything; write nothing yet.
21043
21313
  const packageJsonPath = path$5.join(outDir, 'package.json');
21044
21314
  if ((await writeTarget(outDir, 'package.json')) !== 'file') {
@@ -21067,9 +21337,16 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21067
21337
  const packageManager = packageManagerInfo.name;
21068
21338
  const inWorkspace = packageManagerInfo.root !== path$5.resolve(outDir);
21069
21339
  const byPath = new Map(files.map((file) => [file.path, file]));
21070
- const existingViteConfig = VITE_CONFIG_NAMES.find((name) => existsSync(path$5.join(outDir, name))) ??
21071
- null;
21072
- const planned = skeletonFiles(files, language).filter((file) => !(file.path.startsWith('vite.config.') && existingViteConfig != null));
21340
+ const viteConfigs = VITE_CONFIG_NAMES.filter((name) => existsSync(path$5.join(outDir, name)));
21341
+ // The one Vite loads; it ignores the rest.
21342
+ const existingViteConfig = viteConfigs[0] ?? null;
21343
+ const esmPackage = existingPackageJson.type === 'module';
21344
+ // Vite loads .cjs/.cts configs, and .js/.ts ones without "type": "module",
21345
+ // as CommonJS, which cannot load the ESM-only @iwsdk/vite-plugin-dev.
21346
+ const commonJsViteConfig = existingViteConfig != null &&
21347
+ (/\.c[jt]s$/u.test(existingViteConfig) ||
21348
+ (!esmPackage && /\.[jt]s$/u.test(existingViteConfig)));
21349
+ const planned = skeletonFiles(files, language, esmPackage).filter((file) => !(file.path.startsWith('vite.config.') && existingViteConfig != null));
21073
21350
  const targets = new Map();
21074
21351
  for (const file of planned) {
21075
21352
  const target = await writeTarget(outDir, file.path);
@@ -21153,6 +21430,8 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21153
21430
  }
21154
21431
  }
21155
21432
  let viteConfig;
21433
+ // The config already had iwsdkDev() before this run.
21434
+ let pluginFound = false;
21156
21435
  if (existingViteConfig == null) {
21157
21436
  const createdConfig = created.find((file) => file.startsWith('vite.config.'));
21158
21437
  viteConfig = { file: createdConfig ?? null, status: 'created' };
@@ -21162,18 +21441,58 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21162
21441
  }
21163
21442
  else {
21164
21443
  const configPath = path$5.join(outDir, existingViteConfig);
21165
- const patched = patchViteConfig(await fsp.readFile(configPath, 'utf8'));
21166
- if (patched.status === 'patched') {
21444
+ const source = await fsp.readFile(configPath, 'utf8');
21445
+ const patched = patchViteConfig(source);
21446
+ pluginFound = patched.status === 'already-configured';
21447
+ let status = patched.status;
21448
+ if (
21449
+ // Adding the plugin to a CommonJS config would stop it from loading,
21450
+ // and with several configs the edit could land where Vite never looks.
21451
+ (status === 'patched' &&
21452
+ (commonJsViteConfig || viteConfigs.length > 1)) ||
21453
+ // A CommonJS config that imports the ESM-only plugin already fails.
21454
+ (pluginFound && commonJsViteConfig && loadsPluginStatically(source))) {
21455
+ status = 'manual';
21456
+ }
21457
+ if (status === 'patched') {
21167
21458
  await fsp.writeFile(configPath, patched.text);
21168
21459
  }
21169
- viteConfig = { file: existingViteConfig, status: patched.status };
21170
- }
21171
- if (viteConfig.status === 'manual') {
21172
- manualSteps.push(`Add the IWSDK plugin to ${viteConfig.file}: \`import { iwsdkDev } from '@iwsdk/vite-plugin-dev'\` and put \`iwsdkDev()\` in the config's top-level \`plugins\` array.`);
21173
- }
21174
- if (existingViteConfig != null &&
21175
- viteConfig.status !== 'already-configured') {
21176
- manualSteps.push(`If the app renders UIKitML panels, also dedupe \`three\` and the \`@pmndrs/uikit*\` packages in ${existingViteConfig} (\`resolve.dedupe\`, \`optimizeDeps.include\`), as the IWSDK starter's Vite config does.`);
21460
+ viteConfig = { file: existingViteConfig, status };
21461
+ }
21462
+ // Where the plugin belongs: the config Vite loads, once it loads as ESM.
21463
+ const pluginConfig = existingViteConfig != null && commonJsViteConfig
21464
+ ? esmConfigName(existingViteConfig)
21465
+ : existingViteConfig;
21466
+ if (existingViteConfig != null && viteConfig.status === 'manual') {
21467
+ const ignored = viteConfigs.slice(1);
21468
+ // A rename onto a config that exists would overwrite it.
21469
+ const esmNameTaken = (name) => viteConfigs.includes(esmConfigName(name));
21470
+ // tsc compiles vite.config.ts to .js (.mts to .mjs, .cts to .cjs), and
21471
+ // its next run replaces an edit to the output.
21472
+ const compiledFrom = ignored.find((name) => name === existingViteConfig.replace(/js$/u, 'ts'));
21473
+ manualSteps.push([
21474
+ ignored.length > 0 &&
21475
+ `Vite loads ${existingViteConfig} and ignores ${ignored.join(', ')}, so Create edited none of them.`,
21476
+ commonJsViteConfig &&
21477
+ `Vite loads ${existingViteConfig} as CommonJS and the IWSDK plugin is ESM-only: ${esmNameTaken(existingViteConfig)
21478
+ ? `merge it into ${pluginConfig} (which already exists) and delete ${existingViteConfig}, then update`
21479
+ : `rename it to ${pluginConfig} (ES module syntax) and update`} what refers to ${existingViteConfig}, such as \`include\` in tsconfig.node.json or \`--config ${existingViteConfig}\` in package.json scripts.`,
21480
+ !pluginFound &&
21481
+ `Add the IWSDK plugin to ${pluginConfig}: \`import { iwsdkDev } from '@iwsdk/vite-plugin-dev'\` and put \`iwsdkDev()\` in the config's top-level \`plugins\` array.`,
21482
+ compiledFrom != null &&
21483
+ `If ${existingViteConfig} is compiled from ${compiledFrom}, delete it and ${
21484
+ // The source loads as CommonJS too, so it needs the ESM name.
21485
+ commonJsViteConfig
21486
+ ? `make those changes to ${compiledFrom} instead, ${esmNameTaken(compiledFrom)
21487
+ ? `merging it into ${esmConfigName(compiledFrom)} (which already exists)`
21488
+ : `renaming it to ${esmConfigName(compiledFrom)}`}`
21489
+ : `add the plugin to ${compiledFrom} instead`}.`,
21490
+ ]
21491
+ .filter(Boolean)
21492
+ .join(' '));
21493
+ }
21494
+ if (existingViteConfig != null && !pluginFound) {
21495
+ manualSteps.push(`If the app renders UIKitML panels, also dedupe \`three\` and the \`@pmndrs/uikit*\` packages in ${pluginConfig} (\`resolve.dedupe\`, \`optimizeDeps.include\`), as the IWSDK starter's Vite config does.`);
21177
21496
  }
21178
21497
  const gitignoreAdded = [];
21179
21498
  if ((await writeTarget(outDir, '.gitignore')) !== 'blocked') {
@@ -21206,6 +21525,29 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21206
21525
  manualSteps.push(`Load IWSDK from your app: add \`import '${importSpec}';\` to ${entryFile}, or add \`<script type="module" src="/${entry}"></script>\` to index.html. It calls World.create, which adds the 3D canvas.`);
21207
21526
  }
21208
21527
  }
21528
+ // The manifest written now or kept from an earlier run, which may have
21529
+ // turned locomotion on (1.2.0-rc.0 did) over the same empty scene.
21530
+ const manifest = await readJson(path$5.join(outDir, 'iwsdk.config.json'));
21531
+ const world = isRecord$1(manifest) && isRecord$1(manifest.world) ? manifest.world : {};
21532
+ const locomotion = isRecord$1(world.features)
21533
+ ? world.features.locomotion
21534
+ : undefined;
21535
+ if (locomotion && isRecord$1(manifest) && typeof manifest.scene === 'string') {
21536
+ const sceneFile = path$5.resolve(outDir, manifest.scene);
21537
+ const scene = await readJson(sceneFile);
21538
+ if (scene != null && !hasLocomotionEnvironment(scene)) {
21539
+ manualSteps.push(`Locomotion is on in iwsdk.config.json, but ${path$5.relative(outDir, sceneFile).split(path$5.sep).join('/')} has no \`LocomotionEnvironment\`: add it to the floor the player walks on, or set \`world.features.locomotion\` to \`false\`. Otherwise the player falls through the world.`);
21540
+ }
21541
+ }
21542
+ const locomotionOff = created.includes('iwsdk.config.json') &&
21543
+ created.some((file) => file.endsWith('.iwsdk.scene.json')) &&
21544
+ !locomotion &&
21545
+ (world.xr === false || (isRecord$1(world.xr) && world.xr.mode === 'vr'))
21546
+ ? {
21547
+ target: world.xr === false ? 'browser' : 'vr',
21548
+ requested: locomotionOffRequested,
21549
+ }
21550
+ : null;
21209
21551
  if (merge.report.keptScripts.includes('dev')) {
21210
21552
  manualSteps.push(`Your \`dev\` script was kept. Start the IWSDK-managed runtime with \`${runScriptCommand(packageManager, 'iwsdk:dev')}\` or \`npx @iwsdk/cli dev up\`.`);
21211
21553
  }
@@ -21226,6 +21568,7 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21226
21568
  packageJson: merge.report,
21227
21569
  overrides,
21228
21570
  viteConfig,
21571
+ locomotionOff,
21229
21572
  gitignoreAdded,
21230
21573
  guidance,
21231
21574
  manualSteps,
@@ -21261,8 +21604,16 @@ function printAdoptReport(report, outcome) {
21261
21604
  created: `created ${report.viteConfig.file}`,
21262
21605
  patched: `added iwsdkDev() to ${report.viteConfig.file}`,
21263
21606
  'already-configured': `${report.viteConfig.file} already uses iwsdkDev()`,
21264
- manual: `could not edit ${report.viteConfig.file} safely`,
21607
+ manual: `left ${report.viteConfig.file} unchanged; see "To finish"`,
21265
21608
  }[report.viteConfig.status]}`);
21609
+ if (report.locomotionOff) {
21610
+ const { target, requested } = report.locomotionOff;
21611
+ lines.push(` Locomotion: ${requested
21612
+ ? 'off'
21613
+ : 'left off, because the new scene has no floor to stand on'}. To turn it on, give your floor a \`LocomotionEnvironment\` component, then ${target === 'browser'
21614
+ ? 'set `world.features.locomotion` in iwsdk.config.json to `{ "browserControls": true }`: browser keyboard and gamepad controls are off by default.'
21615
+ : 'enable `world.features.locomotion` in iwsdk.config.json.'}`);
21616
+ }
21266
21617
  if (report.gitignoreAdded.length > 0) {
21267
21618
  lines.push(` .gitignore: added ${report.gitignoreAdded.join(', ')}`);
21268
21619
  }
@@ -22469,7 +22820,7 @@ function createProjectManifest(configuration) {
22469
22820
  };
22470
22821
  }
22471
22822
 
22472
- const VERSION = "1.2.0-rc.0";
22823
+ const VERSION = "1.2.0-rc.1";
22473
22824
  const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
22474
22825
 
22475
22826
  /**
@@ -22647,6 +22998,11 @@ function targetHasContent(target) {
22647
22998
  }
22648
22999
  return fs$2.readdirSync(target.outDir).length > 0;
22649
23000
  }
23001
+ /** A target with a package.json: Create adds IWSDK to it, never over it. */
23002
+ function isExistingProject(target) {
23003
+ return (targetHasContent(target) &&
23004
+ fs$2.existsSync(path$5.join(target.outDir, 'package.json')));
23005
+ }
22650
23006
  function toPackageName(value) {
22651
23007
  const normalized = value
22652
23008
  .trim()
@@ -28997,6 +29353,7 @@ async function promptFlow(nameArg, defaults = {}) {
28997
29353
  let gitInit = true;
28998
29354
  let installNow = true;
28999
29355
  let configuration = getRecommendedConfiguration(target);
29356
+ const overrides = {};
29000
29357
  if (setup === 'advanced') {
29001
29358
  const languageAnswer = await prompts$1({
29002
29359
  type: 'select',
@@ -29010,17 +29367,22 @@ async function promptFlow(nameArg, defaults = {}) {
29010
29367
  }, { onCancel });
29011
29368
  assertNotCancelled();
29012
29369
  language = languageAnswer.language || 'ts';
29013
- const overrides = {};
29370
+ // An existing project gets an empty scene with nothing to stand on, so
29371
+ // locomotion starts off there.
29372
+ const adopting = defaults.isExistingProject?.(name) ?? false;
29014
29373
  for (const key of ADVANCED_FEATURE_KEYS) {
29015
29374
  const definition = FEATURE_CATALOG[key];
29016
29375
  if (!definition.targets.includes(target)) {
29017
29376
  continue;
29018
29377
  }
29378
+ const needsFloor = adopting && key === 'locomotionEnabled';
29019
29379
  const answer = await prompts$1({
29020
29380
  type: 'toggle',
29021
29381
  name: 'enabled',
29022
- message: `${definition.label}: ${definition.description}`,
29023
- initial: !!configuration.featureFlags[key],
29382
+ message: `${definition.label}: ${definition.description}${needsFloor
29383
+ ? ' Needs a floor with LocomotionEnvironment, which the new scene does not have yet.'
29384
+ : ''}`,
29385
+ initial: needsFloor ? false : !!configuration.featureFlags[key],
29024
29386
  active: 'Yes',
29025
29387
  inactive: 'No',
29026
29388
  }, { onCancel });
@@ -29058,6 +29420,7 @@ async function promptFlow(nameArg, defaults = {}) {
29058
29420
  mode: configuration.mode,
29059
29421
  language,
29060
29422
  featureFlags: configuration.featureFlags,
29423
+ featureOverrides: overrides,
29061
29424
  gitInit,
29062
29425
  xrFeatureStates: configuration.xrFeatureStates,
29063
29426
  actionItems: [],
@@ -29659,12 +30022,17 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29659
30022
  mode: configuration.mode,
29660
30023
  language,
29661
30024
  featureFlags: configuration.featureFlags,
30025
+ featureOverrides: overrides,
29662
30026
  gitInit: resolveBooleanFlag(process.argv, '--git', '--no-git') ?? true,
29663
30027
  xrFeatureStates: configuration.xrFeatureStates,
29664
30028
  };
29665
30029
  }
29666
30030
  else {
29667
- res = await promptFlow(nameArg, { target: explicitTarget });
30031
+ res = await promptFlow(nameArg, {
30032
+ target: explicitTarget,
30033
+ isExistingProject: (name) => isValidProjectTarget(name) &&
30034
+ isExistingProject(resolveProjectTarget(name, process.cwd())),
30035
+ });
29668
30036
  }
29669
30037
  // Validate the requested directory (both interactive and non-interactive paths).
29670
30038
  if (!isValidProjectTarget(res.name)) {
@@ -29675,8 +30043,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29675
30043
  const hasTargetContent = targetHasContent(projectTarget);
29676
30044
  // An existing package.json means an existing project: adopt IWSDK into it
29677
30045
  // without overwriting anything, even when --force is passed.
29678
- const adopting = hasTargetContent &&
29679
- fs$2.existsSync(join(projectTarget.outDir, 'package.json'));
30046
+ const adopting = isExistingProject(projectTarget);
29680
30047
  if (adopting && cliOpts.canary) {
29681
30048
  throw new Error('--canary installs an SDK bundle into new projects only. Drop --canary to add IWSDK to this existing project.');
29682
30049
  }
@@ -29700,6 +30067,17 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29700
30067
  ? 'ts'
29701
30068
  : 'js';
29702
30069
  }
30070
+ if (adopting &&
30071
+ res.featureFlags.locomotionEnabled &&
30072
+ res.featureOverrides?.locomotionEnabled == null) {
30073
+ // The recommended locomotion assumes the starter's floor. An adopted
30074
+ // project gets an empty scene with nothing to stand on, so the player
30075
+ // would fall forever; locomotion stays opt-in there.
30076
+ Object.assign(res, getRecommendedConfiguration(res.target, {
30077
+ ...res.featureFlags,
30078
+ locomotionEnabled: false,
30079
+ }));
30080
+ }
29703
30081
  printConfigurationSummary(res, adopting);
29704
30082
  const source = resolveSource(cliOpts.canary);
29705
30083
  // Prepare source (downloads tgz files for remote bundles)
@@ -29744,6 +30122,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29744
30122
  if (adopting) {
29745
30123
  await adoptProject(outDir, projectFiles, res.language, {
29746
30124
  install: res.installNow,
30125
+ locomotionOffRequested: res.featureOverrides?.locomotionEnabled === false,
29747
30126
  });
29748
30127
  return;
29749
30128
  }
@@ -29839,6 +30218,7 @@ async function adoptProject(outDir, files, language, options) {
29839
30218
  files,
29840
30219
  guidanceRoot: resolvePackagedGuidanceRoot(),
29841
30220
  language,
30221
+ locomotionOffRequested: options.locomotionOffRequested,
29842
30222
  });
29843
30223
  const outcome = { installed: false, adaptersSynced: false };
29844
30224
  if (options.install) {