@iwsdk/cli 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.
- package/README.md +40 -13
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
- package/dist/agent-guidance/files/.claude/settings.json +1 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
- package/dist/agent-guidance/files/AGENTS.md +1 -1
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
- package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
- package/dist/agent-guidance/files/src/AGENTS.md +1 -1
- package/dist/agent-guidance/manifest.json +111 -11
- package/dist/agent-guidance.d.ts +31 -4
- package/dist/agent-guidance.d.ts.map +1 -1
- package/dist/agent-guidance.js +269 -60
- package/dist/agent-guidance.js.map +1 -1
- package/dist/cli.js +1128 -131
- package/dist/cli.js.map +1 -1
- package/dist/commands/upgrade.d.ts +87 -0
- package/dist/commands/upgrade.d.ts.map +1 -1
- package/dist/guidance-refresh.d.ts +23 -3
- package/dist/guidance-refresh.d.ts.map +1 -1
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1128 -131
- package/dist/index.js.map +1 -1
- package/dist/metavr-telemetry.d.ts +6 -0
- package/dist/metavr-telemetry.d.ts.map +1 -1
- package/dist/package-manager.d.ts +6 -0
- package/dist/package-manager.d.ts.map +1 -1
- package/dist/release-notes.json +132 -0
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
package/dist/agent-guidance.js
CHANGED
|
@@ -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,
|
|
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
|
-
/**
|
|
2591
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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 (
|
|
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,
|
|
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
|
-
...
|
|
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 =
|
|
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 =
|
|
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 =
|
|
3028
|
-
return name != null &&
|
|
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
|
-
|
|
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
|
|
3145
|
-
const
|
|
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
|
-
|
|
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' ||
|
|
3182
|
-
|
|
3183
|
-
|
|
3184
|
-
|
|
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 {
|
|
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
|
|
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
|
-
|
|
3285
|
-
//
|
|
3286
|
-
|
|
3287
|
-
|
|
3288
|
-
|
|
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
|
-
|
|
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
|
-
|
|
3446
|
+
result = await syncFileUnit(unit, source, writer, force, create(unit));
|
|
3302
3447
|
break;
|
|
3303
3448
|
case 'block':
|
|
3304
|
-
|
|
3449
|
+
result = await syncBlockUnit(unit, source, writer, force, create(unit));
|
|
3305
3450
|
break;
|
|
3306
3451
|
case 'claude-import':
|
|
3307
|
-
|
|
3452
|
+
result = await syncClaudeImport(unit, source, writer, force, create(unit), !onlyExisting || holdsRootBlock());
|
|
3308
3453
|
break;
|
|
3309
3454
|
case 'claude-settings':
|
|
3310
|
-
|
|
3311
|
-
|
|
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
|
-
|
|
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
|