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

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 (103) hide show
  1. package/README.md +40 -13
  2. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
  3. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  33. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  34. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  35. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
  36. package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
  37. package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
  38. package/dist/agent-guidance/files/.claude/settings.json +2 -0
  39. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  40. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  41. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  42. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  43. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
  44. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
  45. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  46. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
  47. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  70. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  71. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  72. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
  73. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
  74. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  75. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  76. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  77. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  78. package/dist/agent-guidance/files/AGENTS.md +10 -1
  79. package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
  80. package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
  81. package/dist/agent-guidance/files/src/AGENTS.md +1 -1
  82. package/dist/agent-guidance/manifest.json +142 -12
  83. package/dist/agent-guidance.d.ts +31 -4
  84. package/dist/agent-guidance.d.ts.map +1 -1
  85. package/dist/agent-guidance.js +269 -60
  86. package/dist/agent-guidance.js.map +1 -1
  87. package/dist/cli.js +1128 -131
  88. package/dist/cli.js.map +1 -1
  89. package/dist/commands/upgrade.d.ts +87 -0
  90. package/dist/commands/upgrade.d.ts.map +1 -1
  91. package/dist/guidance-refresh.d.ts +23 -3
  92. package/dist/guidance-refresh.d.ts.map +1 -1
  93. package/dist/help.d.ts.map +1 -1
  94. package/dist/index.d.ts.map +1 -1
  95. package/dist/index.js +1128 -131
  96. package/dist/index.js.map +1 -1
  97. package/dist/metavr-telemetry.d.ts +6 -0
  98. package/dist/metavr-telemetry.d.ts.map +1 -1
  99. package/dist/package-manager.d.ts +6 -0
  100. package/dist/package-manager.d.ts.map +1 -1
  101. package/dist/release-notes.json +183 -0
  102. package/dist/version.d.ts +1 -1
  103. package/package.json +1 -1
@@ -22,6 +22,11 @@ export interface GuidanceManifest {
22
22
  version: string;
23
23
  units: GuidanceUnit[];
24
24
  legacy: Record<string, string[]>;
25
+ /**
26
+ * Retired unit path -> the units of this release that replace it (an empty
27
+ * list retires it outright). Older manifests do not have it.
28
+ */
29
+ successors?: Record<string, string[]>;
25
30
  }
26
31
  export interface GuidanceSource {
27
32
  /** Directory holding manifest.json and files/. */
@@ -36,9 +41,14 @@ export interface GuidanceUnitResult {
36
41
  kind: UnitKind;
37
42
  action: GuidanceAction;
38
43
  /** Why a unit was skipped, or how it was updated. */
39
- reason?: 'modified' | 'unmanaged' | 'legacy-modified' | 'malformed-block' | 'invalid-json' | 'newer' | 'forced' | 'appended' | 'legacy';
40
- /** What to do about a skipped unit, when that needs more than --force. */
44
+ reason?: 'modified' | 'unmanaged' | 'legacy-modified' | 'malformed-block' | 'invalid-json' | 'newer' | 'missing' | 'retired' | 'forced' | 'appended' | 'legacy';
45
+ /**
46
+ * What to do about a skipped unit, when that needs more than --force. For
47
+ * `missing`, what an existing file lacks.
48
+ */
41
49
  detail?: string;
50
+ /** For a removed retired unit, the units that replace it. */
51
+ replacedBy?: string[];
42
52
  }
43
53
  export interface GuidanceSkillSummary {
44
54
  name: string;
@@ -66,6 +76,19 @@ export interface SyncAgentGuidanceOptions {
66
76
  force?: boolean;
67
77
  /** Report what would change without writing. */
68
78
  dryRun?: boolean;
79
+ /**
80
+ * Refresh only the guidance the project already has. Unedited units are
81
+ * updated, but a missing file, skill folder, AGENTS.md block or CLAUDE.md
82
+ * import is not created, and no skill permission is granted; those units
83
+ * come back skipped with reason `missing`. A migration is done whole: a
84
+ * retired unit is removed only when the manifest names what replaces it,
85
+ * and its successors are written in the same run (a successor skill gets
86
+ * the permission its predecessor had); a CLAUDE.md from before 1.0 that
87
+ * holds the full guidance becomes an `@AGENTS.md` import only together with
88
+ * the AGENTS.md block. Other retired units are kept, skipped with reason
89
+ * `retired`.
90
+ */
91
+ onlyExisting?: boolean;
69
92
  }
70
93
  export declare class GuidanceSourceError extends Error {
71
94
  readonly code: 'core_not_installed' | 'core_without_guidance' | 'guidance_unavailable' | 'unsupported_guidance_format';
@@ -74,6 +97,8 @@ export declare class GuidanceSourceError extends Error {
74
97
  export declare function fileUnitHash(text: string): string;
75
98
  export declare function directoryUnitHash(files: ReadonlyMap<string, string | Buffer>): string;
76
99
  export declare function blockUnitHash(body: string): string;
100
+ /** The release stamped on the iwsdk-agent-guidance block in `text`, if any. */
101
+ export declare function readGuidanceBlockVersion(text: string): string | null;
77
102
  export declare function loadGuidanceSource(root: string, origin?: GuidanceSource['origin']): Promise<GuidanceSource>;
78
103
  /** Version of `@iwsdk/core` installed for the project, or null. */
79
104
  export declare function readInstalledCoreVersion(projectRoot: string): string | null;
@@ -94,9 +119,11 @@ export declare function ownedSkillNames(manifest: GuidanceManifest): Set<string>
94
119
  /**
95
120
  * Write a guidance release into a project. Files IWSDK wrote and nobody edited
96
121
  * are replaced; edited files and files IWSDK does not own are reported and left
97
- * alone unless `force` is set; retired IWSDK files are removed.
122
+ * alone unless `force` is set; retired IWSDK files are removed once what
123
+ * replaces them is in place. Missing units are created unless `onlyExisting`
124
+ * is set (see there).
98
125
  */
99
- export declare function syncAgentGuidance({ projectRoot, source, tools, force, dryRun, }: SyncAgentGuidanceOptions): Promise<SyncAgentGuidanceResult>;
126
+ export declare function syncAgentGuidance({ projectRoot, source, tools, force, dryRun, onlyExisting, }: SyncAgentGuidanceOptions): Promise<SyncAgentGuidanceResult>;
100
127
  /**
101
128
  * The project that receives guidance: the nearest directory at or above
102
129
  * `startDirectory` with a package.json. In a monorepo, run from the app's
@@ -1 +1 @@
1
- {"version":3,"file":"agent-guidance.d.ts","sourceRoot":"","sources":["../src/agent-guidance.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"agent-guidance.d.ts","sourceRoot":"","sources":["../src/agent-guidance.ts"],"names":[],"mappings":"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"}
@@ -1,6 +1,6 @@
1
1
  import { createHash } from 'crypto';
2
2
  import { existsSync, readFileSync, realpathSync } from 'fs';
3
- import { readFile, lstat, readdir, rm, mkdir, writeFile, rename, realpath, rmdir } from 'fs/promises';
3
+ import { readFile, lstat, readdir, realpath, rm, mkdir, writeFile, rename, rmdir } from 'fs/promises';
4
4
  import { createRequire } from 'module';
5
5
  import path from 'path';
6
6
  import { fileURLToPath } from 'url';
@@ -2374,6 +2374,8 @@ const GUIDANCE_TOOLS = [
2374
2374
  // test/agent-guidance.test.ts checks both sides against a fresh render.
2375
2375
  const GUIDANCE_FORMAT = 1;
2376
2376
  const BLOCK_NAME = 'iwsdk-agent-guidance';
2377
+ /** The root AGENTS.md block unit, which a CLAUDE.md import points at. */
2378
+ const ROOT_BLOCK = 'AGENTS.md';
2377
2379
  const STAMP_LINE = /^<!-- iwsdk-agent-guidance version=(\S+) sha256=([0-9a-f]{64})(?: name=(\S+))? [^\n]*-->\r?\n?/mu;
2378
2380
  const BLOCK_PATTERN = new RegExp(`<!-- BEGIN ${BLOCK_NAME} version=(\\S+) sha256=([0-9a-f]{64}) -->\\n([\\s\\S]*?)<!-- END ${BLOCK_NAME} -->\\n?`, 'u');
2379
2381
  const BLOCK_BEGIN = new RegExp(`<!-- BEGIN ${BLOCK_NAME}\\b`, 'gu');
@@ -2423,6 +2425,10 @@ function directoryUnitHash(files) {
2423
2425
  function blockUnitHash(body) {
2424
2426
  return sha256(withTrailingNewline(normalizeText(body)));
2425
2427
  }
2428
+ /** The release stamped on the iwsdk-agent-guidance block in `text`, if any. */
2429
+ function readGuidanceBlockVersion(text) {
2430
+ return normalizeText(text).match(BLOCK_PATTERN)?.[1] ?? null;
2431
+ }
2426
2432
  function isTextFile(name) {
2427
2433
  return !/\.(png|jpe?g|webp|gif|glb|mp3|ktx2)$/iu.test(name);
2428
2434
  }
@@ -2485,6 +2491,12 @@ async function loadGuidanceSource(root, origin = 'explicit') {
2485
2491
  assertRelativeUnitPath(file);
2486
2492
  }
2487
2493
  }
2494
+ for (const [retired, successors] of Object.entries(manifest.successors ?? {})) {
2495
+ assertRelativeUnitPath(retired);
2496
+ for (const successor of successors) {
2497
+ assertRelativeUnitPath(successor);
2498
+ }
2499
+ }
2488
2500
  return { root, manifest, origin };
2489
2501
  }
2490
2502
  function bundledGuidanceRoot() {
@@ -2587,11 +2599,14 @@ async function isSameFile(first, second) {
2587
2599
  return false;
2588
2600
  }
2589
2601
  }
2590
- /** Temporary siblings a sync left behind when it was killed mid-swap. */
2591
- const TEMPORARY_SIBLING = /^\..+\.iwsdk-(?:new|old)-(\d+)-(\d+)$/u;
2602
+ /**
2603
+ * Temporary siblings a sync left behind when it was killed mid-swap: the
2604
+ * name they stand in for, `new` or `old`, the process id and the time.
2605
+ */
2606
+ const TEMPORARY_SIBLING = /^\.(.+)\.iwsdk-(new|old)-(\d+)-(\d+)$/u;
2592
2607
  /** A temporary sibling that a sync running right now may still need. */
2593
2608
  function isInUse(name) {
2594
- const [, pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
2609
+ const [, , , pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
2595
2610
  if (Date.now() - Number(createdAt) < 10 * 60_000) {
2596
2611
  return true;
2597
2612
  }
@@ -2748,6 +2763,19 @@ function replacementResult(unit, ownership, force) {
2748
2763
  }
2749
2764
  return null;
2750
2765
  }
2766
+ /**
2767
+ * A unit that `onlyExisting` left out because the project does not have it.
2768
+ * `lacks` names what an existing file is missing.
2769
+ */
2770
+ function missingResult(unit, unitPath = unit.path, lacks) {
2771
+ return {
2772
+ path: unitPath,
2773
+ kind: unit.kind,
2774
+ action: 'skipped',
2775
+ reason: 'missing',
2776
+ ...(lacks ? { detail: lacks } : {}),
2777
+ };
2778
+ }
2751
2779
  async function pathKind(filePath) {
2752
2780
  try {
2753
2781
  const stat = await lstat(filePath);
@@ -2760,7 +2788,13 @@ async function pathKind(filePath) {
2760
2788
  throw error;
2761
2789
  }
2762
2790
  }
2763
- async function syncDirectoryUnit(unit, source, writer, force) {
2791
+ /**
2792
+ * The unit syncs below take `create`: whether a unit the project lacks (a
2793
+ * missing file or folder, or a block or import missing from a file) may be
2794
+ * written. `onlyExisting` allows it only for units that replace guidance
2795
+ * this run retires, and for folders a killed sync was replacing.
2796
+ */
2797
+ async function syncDirectoryUnit(unit, source, writer, force, create) {
2764
2798
  const localRoot = path.join(writer.projectRoot, unit.path);
2765
2799
  const replace = async () => {
2766
2800
  const files = [];
@@ -2772,6 +2806,9 @@ async function syncDirectoryUnit(unit, source, writer, force) {
2772
2806
  const kind = await pathKind(localRoot);
2773
2807
  const localFiles = kind === 'directory' ? await readTree(localRoot) : null;
2774
2808
  if (kind === 'missing' || localFiles?.size === 0) {
2809
+ if (!create) {
2810
+ return missingResult(unit);
2811
+ }
2775
2812
  await replace();
2776
2813
  return { path: unit.path, kind: unit.kind, action: 'created' };
2777
2814
  }
@@ -2805,10 +2842,13 @@ async function syncDirectoryUnit(unit, source, writer, force) {
2805
2842
  }
2806
2843
  return result;
2807
2844
  }
2808
- async function syncFileUnit(unit, source, writer, force) {
2845
+ async function syncFileUnit(unit, source, writer, force, create) {
2809
2846
  const local = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2810
2847
  const next = await readSourceFile(source, unit.path);
2811
2848
  if (local == null) {
2849
+ if (!create) {
2850
+ return missingResult(unit);
2851
+ }
2812
2852
  await writer.write(unit.path, next);
2813
2853
  return { path: unit.path, kind: unit.kind, action: 'created' };
2814
2854
  }
@@ -2822,10 +2862,13 @@ async function syncFileUnit(unit, source, writer, force) {
2822
2862
  }
2823
2863
  return result;
2824
2864
  }
2825
- async function syncBlockUnit(unit, source, writer, force) {
2865
+ async function syncBlockUnit(unit, source, writer, force, create) {
2826
2866
  const local = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2827
2867
  const block = (await readSourceFile(source, unit.path)).toString('utf8');
2828
2868
  if (local == null) {
2869
+ if (!create) {
2870
+ return missingResult(unit);
2871
+ }
2829
2872
  await writer.write(unit.path, block);
2830
2873
  return { path: unit.path, kind: unit.kind, action: 'created' };
2831
2874
  }
@@ -2884,6 +2927,10 @@ async function syncBlockUnit(unit, source, writer, force) {
2884
2927
  reason: 'forced',
2885
2928
  };
2886
2929
  }
2930
+ if (!create) {
2931
+ // No IWSDK block: the developer removed it or replaced the file.
2932
+ return missingResult(unit, unit.path, 'no iwsdk-agent-guidance block');
2933
+ }
2887
2934
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(normalized)}${normalized.trim() ? '\n' : ''}${block}`, local));
2888
2935
  return {
2889
2936
  path: unit.path,
@@ -2892,23 +2939,54 @@ async function syncBlockUnit(unit, source, writer, force) {
2892
2939
  reason: 'appended',
2893
2940
  };
2894
2941
  }
2895
- async function syncClaudeImport(unit, source, writer, force) {
2942
+ /**
2943
+ * A root CLAUDE.md that holds the full guidance of a release before 1.0, as
2944
+ * that release wrote it. It is replaced with an `@AGENTS.md` import, so the
2945
+ * guidance it held now comes from the AGENTS.md block.
2946
+ */
2947
+ async function holdsLegacyClaudeGuidance(unit, source, projectRoot) {
2948
+ const filePath = path.join(projectRoot, unit.path);
2949
+ const rootFile = await readTextIfExists(filePath);
2950
+ if (rootFile == null ||
2951
+ (await isSameFile(filePath, path.join(projectRoot, ROOT_BLOCK)))) {
2952
+ return false;
2953
+ }
2954
+ const hash = fileUnitHash(rootFile);
2955
+ return (hash !==
2956
+ fileUnitHash((await readSourceFile(source, unit.path)).toString()) &&
2957
+ (source.manifest.legacy[unit.path]?.includes(hash) ?? false));
2958
+ }
2959
+ /**
2960
+ * `replaceLegacy`: whether a CLAUDE.md holding the full guidance of a release
2961
+ * before 1.0 may become an import, which needs the AGENTS.md block in place.
2962
+ */
2963
+ async function syncClaudeImport(unit, source, writer, force, create, replaceLegacy) {
2896
2964
  const rootFile = await readTextIfExists(path.join(writer.projectRoot, unit.path));
2897
2965
  const nestedFile = await readTextIfExists(path.join(writer.projectRoot, '.claude', 'CLAUDE.md'));
2898
2966
  const next = await readSourceFile(source, unit.path);
2899
2967
  if (rootFile == null && nestedFile == null) {
2968
+ if (!create) {
2969
+ return missingResult(unit);
2970
+ }
2900
2971
  await writer.write(unit.path, next);
2901
2972
  return { path: unit.path, kind: unit.kind, action: 'created' };
2902
2973
  }
2903
2974
  if (rootFile != null &&
2904
- (await isSameFile(path.join(writer.projectRoot, unit.path), path.join(writer.projectRoot, 'AGENTS.md')))) {
2975
+ (await isSameFile(path.join(writer.projectRoot, unit.path), path.join(writer.projectRoot, ROOT_BLOCK)))) {
2905
2976
  // CLAUDE.md is a link to AGENTS.md: Claude already reads the guidance.
2906
2977
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2907
2978
  }
2908
- if (rootFile != null &&
2909
- fileUnitHash(rootFile) !== fileUnitHash(next.toString('utf8')) &&
2910
- source.manifest.legacy[unit.path]?.includes(fileUnitHash(rootFile))) {
2979
+ if (await holdsLegacyClaudeGuidance(unit, source, writer.projectRoot)) {
2911
2980
  // Releases before 1.0 put the full guidance in CLAUDE.md.
2981
+ if (!replaceLegacy) {
2982
+ return {
2983
+ path: unit.path,
2984
+ kind: unit.kind,
2985
+ action: 'skipped',
2986
+ reason: 'retired',
2987
+ 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.',
2988
+ };
2989
+ }
2912
2990
  await writer.write(unit.path, withLineEndings(next.toString('utf8'), rootFile));
2913
2991
  return {
2914
2992
  path: unit.path,
@@ -2941,6 +3019,10 @@ async function syncClaudeImport(unit, source, writer, force) {
2941
3019
  (nestedFile != null && /^@\.\.\/AGENTS\.md\s*$/mu.test(nestedFile))) {
2942
3020
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
2943
3021
  }
3022
+ if (!create) {
3023
+ // The import was removed, or CLAUDE.md replaced.
3024
+ return missingResult(unit, rootFile != null ? unit.path : '.claude/CLAUDE.md', 'no @AGENTS.md import');
3025
+ }
2944
3026
  if (rootFile != null) {
2945
3027
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(rootFile)}\n@AGENTS.md\n`, rootFile));
2946
3028
  return {
@@ -2974,9 +3056,12 @@ function ownedSkillNames(manifest) {
2974
3056
  }
2975
3057
  return names;
2976
3058
  }
2977
- async function syncClaudeSettings(unit, source, writer, installedSkills, retiredSkills, force) {
3059
+ async function syncClaudeSettings(unit, source, writer, skills, force, onlyExisting, create) {
2978
3060
  const filePath = path.join(writer.projectRoot, unit.path);
2979
3061
  const raw = await readTextIfExists(filePath);
3062
+ if (raw == null && !create) {
3063
+ return missingResult(unit);
3064
+ }
2980
3065
  let settings = {};
2981
3066
  if (raw != null) {
2982
3067
  let parsed;
@@ -3008,24 +3093,34 @@ async function syncClaudeSettings(unit, source, writer, installedSkills, retired
3008
3093
  const shipped = new Set(unit.skills ?? []);
3009
3094
  const owned = new Set([
3010
3095
  ...ownedSkillNames(source.manifest),
3011
- ...retiredSkills,
3096
+ ...skills.removed,
3012
3097
  ]);
3098
+ const skillOf = (rule) => typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
3099
+ const allowed = new Set(allow.map(skillOf));
3013
3100
  // Grant skills this sync installed (all of them for a new settings file);
3014
3101
  // a permission the developer removed for an untouched skill stays removed.
3015
3102
  // Grant every shipped skill when the file is new, when --force is given, or
3016
3103
  // when no IWSDK skill permission is left (after `adapter prune`, say).
3104
+ // `onlyExisting` grants a skill only the permission of the retired skill it
3105
+ // replaces, and keeps the permissions of retired skills that stay.
3017
3106
  const grantAll = raw == null ||
3018
3107
  force ||
3019
3108
  !allow.some((rule) => {
3020
- const name = typeof rule === 'string'
3021
- ? rule.match(SKILL_PERMISSION)?.[1]
3022
- : undefined;
3109
+ const name = skillOf(rule);
3023
3110
  return name != null && owned.has(name);
3024
3111
  });
3025
- const grant = [...shipped].filter((name) => grantAll || installedSkills.has(name));
3112
+ const grant = onlyExisting && raw != null
3113
+ ? [...skills.replacedBy]
3114
+ .filter(([retired]) => allowed.has(retired))
3115
+ .flatMap(([, successors]) => successors)
3116
+ .filter((name) => shipped.has(name))
3117
+ : [...shipped].filter((name) => grantAll || skills.installed.has(name));
3026
3118
  const isRetired = (rule) => {
3027
- const name = typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
3028
- return name != null && owned.has(name) && !shipped.has(name);
3119
+ const name = skillOf(rule);
3120
+ return (name != null &&
3121
+ owned.has(name) &&
3122
+ !shipped.has(name) &&
3123
+ !(onlyExisting && skills.kept.has(name)));
3029
3124
  };
3030
3125
  const nextAllow = allow.filter((rule) => !isRetired(rule));
3031
3126
  for (const name of grant) {
@@ -3103,7 +3198,14 @@ function toolsForPath(unitPath) {
3103
3198
  }
3104
3199
  return GUIDANCE_TOOLS;
3105
3200
  }
3106
- async function pruneRetiredUnits(source, tools, writer) {
3201
+ /**
3202
+ * IWSDK units in the project that this release no longer ships, for the
3203
+ * selected tools. Also returns the temporary siblings a killed sync left
3204
+ * behind, for the caller to delete once its writes are done, and the units
3205
+ * such a sync was replacing when it was killed (their folder is gone, so
3206
+ * they count as present).
3207
+ */
3208
+ async function findRetiredUnits(source, tools, writer) {
3107
3209
  const shipped = new Set(source.manifest.units.map((unit) => unit.path));
3108
3210
  const blocks = new Set(source.manifest.units
3109
3211
  .filter((unit) => unit.kind === 'block' || unit.kind === 'claude-import')
@@ -3141,8 +3243,9 @@ async function pruneRetiredUnits(source, tools, writer) {
3141
3243
  }
3142
3244
  }
3143
3245
  }
3144
- const results = [];
3145
- const removedSkills = new Set();
3246
+ const retired = [];
3247
+ const interrupted = new Set();
3248
+ const leftovers = [];
3146
3249
  for (const directory of ['.', ...PRUNE_ROOTS.map((root) => root.directory)]) {
3147
3250
  let entries;
3148
3251
  try {
@@ -3152,7 +3255,15 @@ async function pruneRetiredUnits(source, tools, writer) {
3152
3255
  continue;
3153
3256
  }
3154
3257
  for (const name of entries.filter((entry) => TEMPORARY_SIBLING.test(entry) && !isInUse(entry))) {
3155
- await writer.remove(path.posix.join(directory, name));
3258
+ const [, original, label] = TEMPORARY_SIBLING.exec(name);
3259
+ const originalPath = path.posix.join(directory, original);
3260
+ if (label === 'old' &&
3261
+ (await pathKind(path.join(writer.projectRoot, originalPath))) ===
3262
+ 'missing') {
3263
+ // Killed between the two renames of replaceDirectory.
3264
+ interrupted.add(originalPath);
3265
+ }
3266
+ leftovers.push(path.posix.join(directory, name));
3156
3267
  }
3157
3268
  }
3158
3269
  for (const [unitPath, kind] of candidates) {
@@ -3178,24 +3289,13 @@ async function pruneRetiredUnits(source, tools, writer) {
3178
3289
  continue;
3179
3290
  }
3180
3291
  const ownership = classify(localHash, undefined, stamp, source.manifest.legacy[unitPath], source.manifest.version);
3181
- if (ownership === 'managed' || ownership === 'legacy') {
3182
- await writer.remove(unitPath);
3183
- results.push({ path: unitPath, kind, action: 'removed' });
3184
- if (kind === 'directory') {
3185
- removedSkills.add(name);
3186
- }
3187
- }
3188
- else if (ownership === 'modified') {
3189
- // A retired IWSDK unit the developer edited: keep it, but say so.
3190
- results.push({
3191
- path: unitPath,
3192
- kind,
3193
- action: 'skipped',
3194
- reason: 'modified',
3195
- });
3292
+ if (ownership === 'managed' ||
3293
+ ownership === 'legacy' ||
3294
+ ownership === 'modified') {
3295
+ retired.push({ path: unitPath, kind, ownership });
3196
3296
  }
3197
3297
  }
3198
- return { results, removedSkills };
3298
+ return { retired, interrupted, leftovers };
3199
3299
  }
3200
3300
  function readSkillDescription(text) {
3201
3301
  const frontmatter = normalizeText(text).match(/^---\n([\s\S]*?)\n---/u)?.[1];
@@ -3274,44 +3374,153 @@ function buildAgentNotice(source, skills, dryRun, changedCount) {
3274
3374
  /**
3275
3375
  * Write a guidance release into a project. Files IWSDK wrote and nobody edited
3276
3376
  * are replaced; edited files and files IWSDK does not own are reported and left
3277
- * alone unless `force` is set; retired IWSDK files are removed.
3377
+ * alone unless `force` is set; retired IWSDK files are removed once what
3378
+ * replaces them is in place. Missing units are created unless `onlyExisting`
3379
+ * is set (see there).
3278
3380
  */
3279
- async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, }) {
3381
+ async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, onlyExisting = false, }) {
3280
3382
  const writer = createWriter(projectRoot, dryRun);
3281
- const pruned = await pruneRetiredUnits(source, tools, writer);
3383
+ const { retired, interrupted, leftovers } = await findRetiredUnits(source, tools, writer);
3384
+ const units = selectedUnits(source.manifest, tools);
3385
+ const shipped = new Set(source.manifest.units.map((unit) => unit.path));
3386
+ const selected = new Map(units.map((unit) => [unit.path, unit.kind]));
3387
+ // A successor for a coding tool the project does not use is not this
3388
+ // project's, and settings replace no guidance (permissions follow the
3389
+ // skills); one this release does not ship can never be written.
3390
+ const counts = (successor) => shipped.has(successor)
3391
+ ? (selected.get(successor) ?? 'claude-settings') !== 'claude-settings'
3392
+ : true;
3393
+ // Retired units IWSDK wrote and nobody edited are replaced: removed once
3394
+ // the units that replace them are in place. `onlyExisting` replaces only
3395
+ // the ones the release names successors for, and keeps the rest.
3396
+ const replacing = new Map();
3397
+ for (const unit of retired) {
3398
+ const successors = source.manifest.successors?.[unit.path];
3399
+ if (unit.ownership !== 'modified' && (successors || !onlyExisting)) {
3400
+ replacing.set(unit.path, (successors ?? []).filter(counts));
3401
+ }
3402
+ }
3403
+ const claudeImport = units.find((unit) => unit.kind === 'claude-import');
3404
+ const migratesClaude = onlyExisting &&
3405
+ claudeImport != null &&
3406
+ (await holdsLegacyClaudeGuidance(claudeImport, source, projectRoot));
3407
+ // What `onlyExisting` may add: the successors of the guidance this run
3408
+ // replaces, and folders a killed sync was replacing.
3409
+ const additions = new Set([
3410
+ ...[...replacing.values()].flat(),
3411
+ ...(migratesClaude ? [ROOT_BLOCK] : []),
3412
+ ...interrupted,
3413
+ ]);
3414
+ const create = (unit) => !onlyExisting || additions.has(unit.path);
3282
3415
  const results = [];
3416
+ const resultsByUnit = new Map();
3417
+ // In the project once this run is done (in a dry run, once it would be).
3418
+ const present = (unitPath) => {
3419
+ const result = resultsByUnit.get(unitPath);
3420
+ return result !== undefined && result.reason !== 'missing';
3421
+ };
3422
+ // AGENTS.md holds the iwsdk-agent-guidance block once this run is done: not
3423
+ // when it is missing, holds edited guidance from before the block, or has
3424
+ // broken markers.
3425
+ const holdsRootBlock = () => {
3426
+ const reason = resultsByUnit.get(ROOT_BLOCK)?.reason;
3427
+ return (present(ROOT_BLOCK) &&
3428
+ reason !== 'legacy-modified' &&
3429
+ reason !== 'malformed-block');
3430
+ };
3283
3431
  const installedSkills = new Set();
3284
- const units = selectedUnits(source.manifest, tools);
3285
- // Settings last: they grant the skills this run installed.
3286
- for (const unit of [
3287
- ...units.filter((candidate) => candidate.kind !== 'claude-settings'),
3288
- ...units.filter((candidate) => candidate.kind === 'claude-settings'),
3289
- ]) {
3432
+ // The CLAUDE.md import after the AGENTS.md block it points at. Settings
3433
+ // last, once the skills and retired units are settled.
3434
+ const position = (unit) => unit.kind === 'claude-import' ? 1 : unit.kind === 'claude-settings' ? 2 : 0;
3435
+ for (const unit of [...units].sort((left, right) => position(left) - position(right))) {
3436
+ let result;
3290
3437
  switch (unit.kind) {
3291
- case 'directory': {
3292
- const result = await syncDirectoryUnit(unit, source, writer, force);
3438
+ case 'directory':
3439
+ result = await syncDirectoryUnit(unit, source, writer, force, create(unit));
3293
3440
  if (unit.path.startsWith('.claude/') &&
3294
3441
  (result.action === 'created' || result.action === 'updated')) {
3295
3442
  installedSkills.add(path.posix.basename(unit.path));
3296
3443
  }
3297
- results.push(result);
3298
3444
  break;
3299
- }
3300
3445
  case 'file':
3301
- results.push(await syncFileUnit(unit, source, writer, force));
3446
+ result = await syncFileUnit(unit, source, writer, force, create(unit));
3302
3447
  break;
3303
3448
  case 'block':
3304
- results.push(await syncBlockUnit(unit, source, writer, force));
3449
+ result = await syncBlockUnit(unit, source, writer, force, create(unit));
3305
3450
  break;
3306
3451
  case 'claude-import':
3307
- results.push(await syncClaudeImport(unit, source, writer, force));
3452
+ result = await syncClaudeImport(unit, source, writer, force, create(unit), !onlyExisting || holdsRootBlock());
3308
3453
  break;
3309
3454
  case 'claude-settings':
3310
- results.push(await syncClaudeSettings(unit, source, writer, installedSkills, pruned.removedSkills, force));
3311
- break;
3455
+ continue;
3456
+ }
3457
+ results.push(result);
3458
+ resultsByUnit.set(unit.path, result);
3459
+ }
3460
+ const removals = [];
3461
+ const retiredResults = [];
3462
+ for (const unit of retired) {
3463
+ const successors = replacing.get(unit.path);
3464
+ const result = { path: unit.path, kind: unit.kind };
3465
+ if (unit.ownership === 'modified') {
3466
+ // A retired IWSDK unit the developer edited: keep it, but say so.
3467
+ retiredResults.push({ ...result, action: 'skipped', reason: 'modified' });
3468
+ }
3469
+ else if (successors == null) {
3470
+ retiredResults.push({
3471
+ ...result,
3472
+ action: 'skipped',
3473
+ reason: 'retired',
3474
+ detail: `IWSDK ${source.manifest.version} no longer ships it and does not name a replacement; \`npx @iwsdk/cli@latest agents sync\` removes it.`,
3475
+ });
3476
+ }
3477
+ else if (!successors.every(present)) {
3478
+ // Never leave a project with less guidance than it had.
3479
+ retiredResults.push({
3480
+ ...result,
3481
+ action: 'skipped',
3482
+ reason: 'retired',
3483
+ detail: `It stays until ${successors.filter((successor) => !present(successor)).join(', ')} can be written in its place.`,
3484
+ });
3485
+ }
3486
+ else {
3487
+ removals.push(unit);
3488
+ retiredResults.push({
3489
+ ...result,
3490
+ action: 'removed',
3491
+ ...(successors.length > 0 ? { replacedBy: successors } : {}),
3492
+ });
3312
3493
  }
3313
3494
  }
3314
- results.push(...pruned.results);
3495
+ const settings = units.find((unit) => unit.kind === 'claude-settings');
3496
+ if (settings) {
3497
+ const claudeSkill = (unitPath) => unitPath.startsWith('.claude/skills/');
3498
+ const name = (unitPath) => path.posix.basename(unitPath);
3499
+ results.push(await syncClaudeSettings(settings, source, writer, {
3500
+ installed: installedSkills,
3501
+ removed: new Set(removals
3502
+ .filter((unit) => unit.kind === 'directory')
3503
+ .map((unit) => name(unit.path))),
3504
+ kept: new Set(retired
3505
+ .filter((unit) => claudeSkill(unit.path) && !removals.includes(unit))
3506
+ .map((unit) => name(unit.path))),
3507
+ replacedBy: new Map(removals
3508
+ .filter((unit) => claudeSkill(unit.path))
3509
+ .map((unit) => [
3510
+ name(unit.path),
3511
+ replacing.get(unit.path).filter(claudeSkill).map(name),
3512
+ ])),
3513
+ }, force, onlyExisting, create(settings)));
3514
+ }
3515
+ for (const unit of removals) {
3516
+ await writer.remove(unit.path);
3517
+ }
3518
+ // Last: until a folder that a killed sync moved aside is written again,
3519
+ // its moved-aside copy is what tells the next sync to write it.
3520
+ for (const leftover of leftovers) {
3521
+ await writer.remove(leftover);
3522
+ }
3523
+ results.push(...retiredResults);
3315
3524
  const skills = await summarizeSkills(source, tools);
3316
3525
  const changedCount = results.filter((result) => result.action !== 'unchanged' && result.action !== 'skipped').length;
3317
3526
  return {
@@ -3399,5 +3608,5 @@ async function installedGuidanceTools(projectRoot, source) {
3399
3608
  return GUIDANCE_TOOLS.filter((tool) => present.has(tool));
3400
3609
  }
3401
3610
 
3402
- export { GUIDANCE_TOOLS, GuidanceSourceError, blockUnitHash, directoryUnitHash, fileUnitHash, findGuidanceProjectRoot, installedGuidanceTools, loadGuidanceSource, ownedSkillNames, readInstalledCoreVersion, resolveInstalledCorePackageJson, resolveProjectGuidance, syncAgentGuidance };
3611
+ export { GUIDANCE_TOOLS, GuidanceSourceError, blockUnitHash, directoryUnitHash, fileUnitHash, findGuidanceProjectRoot, installedGuidanceTools, loadGuidanceSource, ownedSkillNames, readGuidanceBlockVersion, readInstalledCoreVersion, resolveInstalledCorePackageJson, resolveProjectGuidance, syncAgentGuidance };
3403
3612
  //# sourceMappingURL=agent-guidance.js.map