kerfjs 5.0.0-beta.13 → 5.0.0-beta.131
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/CHANGELOG.md +3384 -108
- package/README.md +101 -37
- package/ai/cursorrules +127 -68
- package/ai/manifest.json +36 -7
- package/ai/skill.md +167 -86
- package/ai/ui-skill.md +18 -0
- package/dist/actions.d.ts +1 -1
- package/dist/actions.js +10 -6
- package/dist/actions.js.map +1 -1
- package/dist/array-signal.js +1 -1
- package/dist/async.d.ts +7 -3
- package/dist/async.js +39 -22
- package/dist/async.js.map +1 -1
- package/dist/attach.js +1 -66
- package/dist/attach.js.map +1 -1
- package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
- package/dist/chunk-4TX6YJDM.js.map +1 -0
- package/dist/{chunk-SVATPF5R.js → chunk-5QDM6HPD.js} +637 -277
- package/dist/chunk-5QDM6HPD.js.map +1 -0
- package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
- package/dist/chunk-5WRGJZV6.js.map +1 -0
- package/dist/chunk-AP2FT33F.js +87 -0
- package/dist/chunk-AP2FT33F.js.map +1 -0
- package/dist/chunk-BTOKH5FA.js +70 -0
- package/dist/chunk-BTOKH5FA.js.map +1 -0
- package/dist/{chunk-ZDCJZCNO.js → chunk-GGADRIQO.js} +168 -97
- package/dist/chunk-GGADRIQO.js.map +1 -0
- package/dist/chunk-KOEGJCIS.js +65 -0
- package/dist/chunk-KOEGJCIS.js.map +1 -0
- package/dist/{chunk-HW7KSM2Y.js → chunk-KUHXPPJ4.js} +1 -1
- package/dist/chunk-KUHXPPJ4.js.map +1 -0
- package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
- package/dist/chunk-MK42GLPV.js.map +1 -0
- package/dist/chunk-N4VHHOCM.js +27 -0
- package/dist/chunk-N4VHHOCM.js.map +1 -0
- package/dist/{chunk-V46JKE44.js → chunk-NRPLVJVR.js} +43 -14
- package/dist/chunk-NRPLVJVR.js.map +1 -0
- package/dist/{chunk-LVH3GC6B.js → chunk-QOAB2ESQ.js} +3 -3
- package/dist/chunk-QOAB2ESQ.js.map +1 -0
- package/dist/{chunk-KZJXHFIB.js → chunk-V322Z7FX.js} +5 -5
- package/dist/chunk-V322Z7FX.js.map +1 -0
- package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
- package/dist/dev.d.ts +46 -15
- package/dist/dev.js +185 -40
- package/dist/dev.js.map +1 -1
- package/dist/html.js +20 -8
- package/dist/html.js.map +1 -1
- package/dist/index.d.ts +98 -13
- package/dist/index.js +49 -21
- package/dist/index.js.map +1 -1
- package/dist/jsx-runtime.d.ts +25 -10
- package/dist/jsx-runtime.js +1 -1
- package/dist/list.d.ts +7 -3
- package/dist/list.js +236 -78
- package/dist/list.js.map +1 -1
- package/dist/overlay.d.ts +287 -142
- package/dist/overlay.js +1040 -369
- package/dist/overlay.js.map +1 -1
- package/dist/remount.js +2 -2
- package/dist/remount.js.map +1 -1
- package/dist/router.d.ts +22 -6
- package/dist/router.js +58 -19
- package/dist/router.js.map +1 -1
- package/dist/scope.d.ts +45 -8
- package/dist/scope.js +69 -30
- package/dist/scope.js.map +1 -1
- package/dist/testing.js +1 -1
- package/dist/timing.d.ts +17 -7
- package/dist/timing.js +8 -3
- package/dist/timing.js.map +1 -1
- package/llms.txt +17 -6
- package/package.json +48 -12
- package/setup/apply.mjs +202 -0
- package/setup/cli.mjs +95 -0
- package/setup/common.mjs +91 -0
- package/setup/detect.mjs +274 -0
- package/setup/index.d.mts +39 -0
- package/setup/index.mjs +1290 -0
- package/setup/jsonc.mjs +201 -0
- package/setup/state.schema.json +57 -0
- package/setup/ui-baseline.mjs +210 -0
- package/dist/chunk-GY4XV2UV.js.map +0 -1
- package/dist/chunk-HW7KSM2Y.js.map +0 -1
- package/dist/chunk-KPXIOG2C.js +0 -54
- package/dist/chunk-KPXIOG2C.js.map +0 -1
- package/dist/chunk-KZJXHFIB.js.map +0 -1
- package/dist/chunk-LVH3GC6B.js.map +0 -1
- package/dist/chunk-QIP723L4.js.map +0 -1
- package/dist/chunk-SVATPF5R.js.map +0 -1
- package/dist/chunk-U6FK33SG.js +0 -20
- package/dist/chunk-U6FK33SG.js.map +0 -1
- package/dist/chunk-UZJ6I4T6.js.map +0 -1
- package/dist/chunk-V46JKE44.js.map +0 -1
- package/dist/chunk-ZDCJZCNO.js.map +0 -1
package/setup/index.mjs
ADDED
|
@@ -0,0 +1,1290 @@
|
|
|
1
|
+
import { readFile, realpath } from 'node:fs/promises';
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
3
|
+
import { dirname, relative, resolve } from 'node:path';
|
|
4
|
+
import process from 'node:process';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
|
|
7
|
+
import {
|
|
8
|
+
contained,
|
|
9
|
+
dependencies,
|
|
10
|
+
describeValue,
|
|
11
|
+
exists,
|
|
12
|
+
parseJsonFile,
|
|
13
|
+
portable,
|
|
14
|
+
readJson,
|
|
15
|
+
readText,
|
|
16
|
+
redactText,
|
|
17
|
+
repositoryRoot,
|
|
18
|
+
sha256,
|
|
19
|
+
shellArg,
|
|
20
|
+
stableJson,
|
|
21
|
+
} from './common.mjs';
|
|
22
|
+
import { detectMode, packageManagerInfo, selectPackage } from './detect.mjs';
|
|
23
|
+
import {
|
|
24
|
+
applyJsoncEdits,
|
|
25
|
+
jsoncInsertProperties,
|
|
26
|
+
jsoncValueEdit,
|
|
27
|
+
parseJsoncDocument,
|
|
28
|
+
} from './jsonc.mjs';
|
|
29
|
+
import {
|
|
30
|
+
uiAppFiles,
|
|
31
|
+
uiDoctorConfig,
|
|
32
|
+
uiEslintTemplate,
|
|
33
|
+
uiPrettierConfig,
|
|
34
|
+
} from './ui-baseline.mjs';
|
|
35
|
+
|
|
36
|
+
export { applyKerfSetup } from './apply.mjs';
|
|
37
|
+
|
|
38
|
+
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
39
|
+
const marker = '<!-- KERF-APP-CANONICAL-END · your customizations below -->';
|
|
40
|
+
|
|
41
|
+
function validateSetupState(state) {
|
|
42
|
+
if (!state || typeof state !== 'object' || Array.isArray(state))
|
|
43
|
+
throw new Error('.kerf-ai-setup.json must be an object.');
|
|
44
|
+
if (![1, 2].includes(state.schemaVersion))
|
|
45
|
+
throw new Error(
|
|
46
|
+
`Unsupported .kerf-ai-setup.json schemaVersion ${state.schemaVersion}.`,
|
|
47
|
+
);
|
|
48
|
+
if (
|
|
49
|
+
typeof state.setupVersion !== 'string' ||
|
|
50
|
+
!['npm', 'pnpm', 'yarn'].includes(state.packageManager) ||
|
|
51
|
+
(state.packageManagerVersion !== undefined &&
|
|
52
|
+
typeof state.packageManagerVersion !== 'string') ||
|
|
53
|
+
(state.packageManagerVariant !== undefined &&
|
|
54
|
+
!['classic', 'berry'].includes(state.packageManagerVariant)) ||
|
|
55
|
+
(state.packageManagerVariant !== undefined &&
|
|
56
|
+
state.packageManager !== 'yarn')
|
|
57
|
+
)
|
|
58
|
+
throw new Error(
|
|
59
|
+
'.kerf-ai-setup.json has invalid version or package-manager metadata.',
|
|
60
|
+
);
|
|
61
|
+
const packageStates =
|
|
62
|
+
state.schemaVersion === 2 ? state.packages : { [state.packagePath]: state };
|
|
63
|
+
if (!packageStates || typeof packageStates !== 'object')
|
|
64
|
+
throw new Error('.kerf-ai-setup.json packages must be an object.');
|
|
65
|
+
for (const [key, value] of Object.entries(packageStates)) {
|
|
66
|
+
if (
|
|
67
|
+
!value ||
|
|
68
|
+
typeof value !== 'object' ||
|
|
69
|
+
value.packagePath !== key ||
|
|
70
|
+
typeof value.package !== 'string' ||
|
|
71
|
+
!['core', 'ui'].includes(value.mode) ||
|
|
72
|
+
!value.managed ||
|
|
73
|
+
typeof value.managed !== 'object' ||
|
|
74
|
+
!value.resolutions ||
|
|
75
|
+
typeof value.resolutions !== 'object'
|
|
76
|
+
)
|
|
77
|
+
throw new Error(`Invalid setup state for package ${key}.`);
|
|
78
|
+
for (const resolution of Object.values(value.resolutions ?? {}))
|
|
79
|
+
if (!['keep', 'kerf', 'skip'].includes(resolution))
|
|
80
|
+
throw new Error(`Invalid persisted resolution for package ${key}.`);
|
|
81
|
+
for (const item of Object.values(value.managed ?? {}))
|
|
82
|
+
if (!item || !/^[a-f0-9]{64}$/.test(item.sha256 ?? ''))
|
|
83
|
+
throw new Error(`Invalid managed-value hash for package ${key}.`);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function allowsVersion(range, version) {
|
|
88
|
+
if (typeof range !== 'string') return false;
|
|
89
|
+
if (range === version || range === '*' || range === 'latest') return true;
|
|
90
|
+
const requested = version
|
|
91
|
+
.match(/^(\d+)\.(\d+)\.(\d+)/)
|
|
92
|
+
?.slice(1)
|
|
93
|
+
.map(Number);
|
|
94
|
+
const declared = range.match(/^(\^|~|>=)\s*(\d+)\.(\d+)\.(\d+)/);
|
|
95
|
+
if (!requested || !declared) return false;
|
|
96
|
+
const base = declared.slice(2).map(Number);
|
|
97
|
+
const compare =
|
|
98
|
+
requested[0] - base[0] || requested[1] - base[1] || requested[2] - base[2];
|
|
99
|
+
if (compare < 0) return false;
|
|
100
|
+
if (declared[1] === '^') return requested[0] === base[0];
|
|
101
|
+
if (declared[1] === '~')
|
|
102
|
+
return requested[0] === base[0] && requested[1] === base[1];
|
|
103
|
+
return true;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function splitCanonical(source) {
|
|
107
|
+
const first = source.indexOf(marker);
|
|
108
|
+
if (first < 0) return { error: 'missing canonical marker' };
|
|
109
|
+
if (source.indexOf(marker, first + marker.length) >= 0)
|
|
110
|
+
return { error: 'multiple canonical markers' };
|
|
111
|
+
const end = first + marker.length + (source[first + marker.length] === '\n');
|
|
112
|
+
return { canonical: source.slice(0, end), append: source.slice(end) };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function mergeCanonical(current, bundled, history, version) {
|
|
116
|
+
if (current === null) return { value: bundled };
|
|
117
|
+
const local = splitCanonical(current);
|
|
118
|
+
if (local.error) return { conflict: local.error };
|
|
119
|
+
const localVersion = current
|
|
120
|
+
.slice(0, 512)
|
|
121
|
+
.match(/kerf-skill-version:\s*([\w.-]+)/)?.[1];
|
|
122
|
+
if (!localVersion) return { conflict: 'missing kerf-skill-version' };
|
|
123
|
+
const expected =
|
|
124
|
+
localVersion === version ? sha256(bundled) : history[localVersion];
|
|
125
|
+
if (!expected || sha256(local.canonical) !== expected)
|
|
126
|
+
return { conflict: 'canonical content was customized above the marker' };
|
|
127
|
+
return { value: bundled + local.append };
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
const hashValue = (value) => sha256(JSON.stringify(value) ?? 'undefined');
|
|
131
|
+
|
|
132
|
+
function reconcileValue({
|
|
133
|
+
target,
|
|
134
|
+
key,
|
|
135
|
+
value,
|
|
136
|
+
id,
|
|
137
|
+
conflicts,
|
|
138
|
+
managedBefore,
|
|
139
|
+
managedAfter,
|
|
140
|
+
resolutions,
|
|
141
|
+
activeConflictIds,
|
|
142
|
+
activeProposalIds,
|
|
143
|
+
knownResolutionIds,
|
|
144
|
+
}) {
|
|
145
|
+
knownResolutionIds.add(id);
|
|
146
|
+
const current = target[key];
|
|
147
|
+
const previouslyManaged = managedBefore[id]?.sha256 === hashValue(current);
|
|
148
|
+
const divergent = key in target && current !== value && !previouslyManaged;
|
|
149
|
+
if (divergent) activeConflictIds.add(id);
|
|
150
|
+
const resolution =
|
|
151
|
+
resolutions[id] === 'skip' && divergent ? undefined : resolutions[id];
|
|
152
|
+
if (divergent && !resolution) {
|
|
153
|
+
conflicts.push({
|
|
154
|
+
id,
|
|
155
|
+
message: `existing value ${describeValue(id, current)} differs from ${describeValue(id, value)}`,
|
|
156
|
+
});
|
|
157
|
+
return;
|
|
158
|
+
}
|
|
159
|
+
if (divergent && resolution === 'keep') return;
|
|
160
|
+
if (!divergent && hashValue(current) !== hashValue(value)) {
|
|
161
|
+
activeProposalIds.add(id);
|
|
162
|
+
if (resolution === 'skip') {
|
|
163
|
+
if (previouslyManaged) managedAfter[id] = managedBefore[id];
|
|
164
|
+
return;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
target[key] = value;
|
|
168
|
+
managedAfter[id] = { sha256: hashValue(value) };
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
function addMapValues(target, additions, path, context) {
|
|
172
|
+
for (const [key, value] of Object.entries(additions)) {
|
|
173
|
+
reconcileValue({ target, key, value, id: `${path}.${key}`, ...context });
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function eslintTemplate(mode, format = 'module') {
|
|
178
|
+
if (mode === 'ui') return uiEslintTemplate(format);
|
|
179
|
+
const preset = mode === 'ui' ? 'recommended-ui' : 'recommended';
|
|
180
|
+
if (format === 'commonjs')
|
|
181
|
+
return `module.exports = (async () => {\n const { default: parser } = await import('@typescript-eslint/parser');\n const { default: kerfjs } = await import('eslint-plugin-kerfjs');\n return [\n { files: ['**/*.{ts,tsx}'], languageOptions: { parser } },\n kerfjs.configs['${preset}'],\n ];\n})();\n`;
|
|
182
|
+
return `import parser from '@typescript-eslint/parser';\nimport kerfjs from 'eslint-plugin-kerfjs';\n\nexport default [\n { files: ['**/*.{ts,tsx}'], languageOptions: { parser } },\n kerfjs.configs['${preset}'],\n];\n`;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
function mergeEslintConfig(source, mode) {
|
|
186
|
+
const imported = source.match(
|
|
187
|
+
/^\s*import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]eslint-plugin-kerfjs['"]\s*;?\s*$/m,
|
|
188
|
+
);
|
|
189
|
+
if (imported) {
|
|
190
|
+
const preset = mode === 'ui' ? 'recommended-ui' : 'recommended';
|
|
191
|
+
const configured = new RegExp(
|
|
192
|
+
`^\\s*${imported[1]}\\.configs\\[['"]${preset}['"]\\],?\\s*$`,
|
|
193
|
+
'm',
|
|
194
|
+
);
|
|
195
|
+
if (configured.test(source)) return { value: source };
|
|
196
|
+
}
|
|
197
|
+
const match = source.match(/^\s*export\s+default\s*\[/m);
|
|
198
|
+
if (!match || (source.includes('`') && !imported))
|
|
199
|
+
return {
|
|
200
|
+
conflict: 'config does not use a provable static export default array',
|
|
201
|
+
};
|
|
202
|
+
const preset = mode === 'ui' ? 'recommended-ui' : 'recommended';
|
|
203
|
+
const importLine = imported
|
|
204
|
+
? ''
|
|
205
|
+
: "import kerfjs from 'eslint-plugin-kerfjs';\n";
|
|
206
|
+
const binding = imported?.[1] ?? 'kerfjs';
|
|
207
|
+
return {
|
|
208
|
+
value: `${importLine}${source.slice(0, match.index + match[0].length)}\n ${binding}.configs['${preset}'],${source.slice(match.index + match[0].length)}`,
|
|
209
|
+
};
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function profileTemplate(packageName, catalogPath, selectionPath) {
|
|
213
|
+
return {
|
|
214
|
+
$schema:
|
|
215
|
+
'https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/application-ui-profile.schema.json',
|
|
216
|
+
schemaVersion: 1,
|
|
217
|
+
scope: 'workspace',
|
|
218
|
+
catalogs: [
|
|
219
|
+
{
|
|
220
|
+
package: packageName,
|
|
221
|
+
...(selectionPath
|
|
222
|
+
? { selection: { path: selectionPath, schemaVersion: 1 } }
|
|
223
|
+
: {}),
|
|
224
|
+
composition: { path: catalogPath, schemaVersion: 1 },
|
|
225
|
+
},
|
|
226
|
+
],
|
|
227
|
+
};
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function metadataTemplate() {
|
|
231
|
+
return {
|
|
232
|
+
$schema:
|
|
233
|
+
'./node_modules/create-kerf-component/component-metadata.schema.json',
|
|
234
|
+
schemaVersion: 1,
|
|
235
|
+
componentCatalog: 'not-applicable',
|
|
236
|
+
components: [],
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
async function installedVersion(directory, name) {
|
|
241
|
+
try {
|
|
242
|
+
const require = createRequire(resolve(directory, 'package.json'));
|
|
243
|
+
let current = dirname(require.resolve(name));
|
|
244
|
+
while (dirname(current) !== current) {
|
|
245
|
+
const manifest = await readJson(resolve(current, 'package.json'));
|
|
246
|
+
if (manifest?.name === name) return manifest.version;
|
|
247
|
+
current = dirname(current);
|
|
248
|
+
}
|
|
249
|
+
} catch {
|
|
250
|
+
return null;
|
|
251
|
+
}
|
|
252
|
+
return null;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
function mergeProfile(current, recommended, context) {
|
|
256
|
+
if (current === undefined) current = {};
|
|
257
|
+
const idPrefix = '.kerf-ui-profile.json';
|
|
258
|
+
if (!current || typeof current !== 'object' || Array.isArray(current)) {
|
|
259
|
+
context.knownResolutionIds.add(idPrefix);
|
|
260
|
+
context.activeConflictIds.add(idPrefix);
|
|
261
|
+
if (!context.resolutions[idPrefix]) {
|
|
262
|
+
context.conflicts.push({
|
|
263
|
+
id: idPrefix,
|
|
264
|
+
message: 'profile root must be an object',
|
|
265
|
+
});
|
|
266
|
+
return current;
|
|
267
|
+
}
|
|
268
|
+
if (context.resolutions[idPrefix] === 'keep') return current;
|
|
269
|
+
current = {};
|
|
270
|
+
}
|
|
271
|
+
const output = JSON.parse(JSON.stringify(current));
|
|
272
|
+
for (const key of ['$schema', 'schemaVersion', 'scope']) {
|
|
273
|
+
reconcileValue({
|
|
274
|
+
target: output,
|
|
275
|
+
key,
|
|
276
|
+
value: recommended[key],
|
|
277
|
+
id: `.kerf-ui-profile.json#${key}`,
|
|
278
|
+
...context,
|
|
279
|
+
});
|
|
280
|
+
}
|
|
281
|
+
if (output.catalogs !== undefined && !Array.isArray(output.catalogs)) {
|
|
282
|
+
const id = `${idPrefix}#catalogs`;
|
|
283
|
+
context.knownResolutionIds.add(id);
|
|
284
|
+
context.activeConflictIds.add(id);
|
|
285
|
+
if (!context.resolutions[id]) {
|
|
286
|
+
context.conflicts.push({ id, message: 'catalogs must be an array' });
|
|
287
|
+
return output;
|
|
288
|
+
}
|
|
289
|
+
if (context.resolutions[id] === 'keep') return output;
|
|
290
|
+
output.catalogs = [];
|
|
291
|
+
}
|
|
292
|
+
output.catalogs ??= [];
|
|
293
|
+
const local = recommended.catalogs[0];
|
|
294
|
+
const existing = output.catalogs.find(
|
|
295
|
+
(item) => item.package === local.package,
|
|
296
|
+
);
|
|
297
|
+
const id = `.kerf-ui-profile.json#catalogs.${local.package}`;
|
|
298
|
+
context.knownResolutionIds.add(id);
|
|
299
|
+
if (!existing) {
|
|
300
|
+
context.activeProposalIds.add(id);
|
|
301
|
+
if (context.resolutions[id] !== 'skip') {
|
|
302
|
+
output.catalogs.push(local);
|
|
303
|
+
context.managedAfter[id] = { sha256: hashValue(local) };
|
|
304
|
+
}
|
|
305
|
+
} else {
|
|
306
|
+
const previouslyManaged =
|
|
307
|
+
context.managedBefore[id]?.sha256 === hashValue(existing);
|
|
308
|
+
const divergent =
|
|
309
|
+
JSON.stringify(existing) !== JSON.stringify(local) && !previouslyManaged;
|
|
310
|
+
if (divergent) context.activeConflictIds.add(id);
|
|
311
|
+
if (
|
|
312
|
+
divergent &&
|
|
313
|
+
(!context.resolutions[id] || context.resolutions[id] === 'skip')
|
|
314
|
+
)
|
|
315
|
+
context.conflicts.push({
|
|
316
|
+
id,
|
|
317
|
+
message: 'existing catalog declaration differs',
|
|
318
|
+
});
|
|
319
|
+
else if (!divergent || context.resolutions[id] === 'kerf') {
|
|
320
|
+
if (hashValue(existing) !== hashValue(local)) {
|
|
321
|
+
context.activeProposalIds.add(id);
|
|
322
|
+
if (context.resolutions[id] === 'skip') {
|
|
323
|
+
context.managedAfter[id] = context.managedBefore[id];
|
|
324
|
+
return output;
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
output.catalogs[output.catalogs.indexOf(existing)] = local;
|
|
328
|
+
context.managedAfter[id] = { sha256: hashValue(local) };
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
return output;
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
/**
|
|
335
|
+
* Validates an explicit or remembered shared-guidance source and returns its
|
|
336
|
+
* workspace-relative path (undefined when there is none).
|
|
337
|
+
*/
|
|
338
|
+
async function validatedGuidanceSource(root, guidanceSource) {
|
|
339
|
+
if (!guidanceSource) return guidanceSource;
|
|
340
|
+
const sourcePath = resolve(root, guidanceSource);
|
|
341
|
+
// KF-G54HNG: a nested package of a repository that is not a workspace
|
|
342
|
+
// shares the repository root's AGENTS.md, above the setup root, so the
|
|
343
|
+
// enclosing repository bounds the source rather than the setup root.
|
|
344
|
+
const boundary = (await repositoryRoot(root)) ?? root;
|
|
345
|
+
if (sourcePath === boundary || !contained(boundary, sourcePath))
|
|
346
|
+
throw new Error(
|
|
347
|
+
'Shared guidance source must be inside the workspace root or its repository.',
|
|
348
|
+
);
|
|
349
|
+
const actualSourcePath = await realpath(sourcePath).catch(() => null);
|
|
350
|
+
if (
|
|
351
|
+
actualSourcePath &&
|
|
352
|
+
!contained(await realpath(boundary), actualSourcePath)
|
|
353
|
+
)
|
|
354
|
+
throw new Error(
|
|
355
|
+
'Shared guidance source must resolve inside the workspace root or its repository.',
|
|
356
|
+
);
|
|
357
|
+
const source = await readText(sourcePath);
|
|
358
|
+
if (
|
|
359
|
+
!source ||
|
|
360
|
+
!/\bkerf(?:js)?\b/i.test(source) ||
|
|
361
|
+
!/(?:kerf:check|npm run check)/i.test(source)
|
|
362
|
+
)
|
|
363
|
+
throw new Error(
|
|
364
|
+
'Shared guidance source must exist and describe Kerf and a project check command.',
|
|
365
|
+
);
|
|
366
|
+
return portable(root, sourcePath);
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
/** Whether two JSON texts hold the same values in the same key order. */
|
|
370
|
+
function sameJson(left, right) {
|
|
371
|
+
try {
|
|
372
|
+
return (
|
|
373
|
+
JSON.stringify(JSON.parse(left)) === JSON.stringify(JSON.parse(right))
|
|
374
|
+
);
|
|
375
|
+
} catch {
|
|
376
|
+
return false;
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** Prettier's configuration file names, as its own search resolves them. */
|
|
381
|
+
const PRETTIER_CONFIG_FILES = [
|
|
382
|
+
'.prettierrc',
|
|
383
|
+
'.prettierrc.json',
|
|
384
|
+
'.prettierrc.yaml',
|
|
385
|
+
'.prettierrc.yml',
|
|
386
|
+
'.prettierrc.json5',
|
|
387
|
+
'.prettierrc.js',
|
|
388
|
+
'.prettierrc.cjs',
|
|
389
|
+
'.prettierrc.mjs',
|
|
390
|
+
'.prettierrc.ts',
|
|
391
|
+
'.prettierrc.cts',
|
|
392
|
+
'.prettierrc.mts',
|
|
393
|
+
'.prettierrc.toml',
|
|
394
|
+
'prettier.config.js',
|
|
395
|
+
'prettier.config.cjs',
|
|
396
|
+
'prettier.config.mjs',
|
|
397
|
+
'prettier.config.ts',
|
|
398
|
+
'prettier.config.cts',
|
|
399
|
+
'prettier.config.mts',
|
|
400
|
+
];
|
|
401
|
+
|
|
402
|
+
/**
|
|
403
|
+
* KF-G54HNG: whether Prettier already resolves a configuration for
|
|
404
|
+
* `directory`, searching it and its ancestors up to the enclosing repository
|
|
405
|
+
* (or the setup root outside one), as Prettier does: a config file or a
|
|
406
|
+
* `prettier` key in a package.json. A package-local config would shadow an
|
|
407
|
+
* ancestor's options and overrides.
|
|
408
|
+
*/
|
|
409
|
+
async function prettierConfigApplies(root, directory) {
|
|
410
|
+
const repository = await repositoryRoot(directory);
|
|
411
|
+
const stop =
|
|
412
|
+
repository && contained(repository, root) ? repository : resolve(root);
|
|
413
|
+
for (let current = directory; ; current = dirname(current)) {
|
|
414
|
+
for (const name of PRETTIER_CONFIG_FILES)
|
|
415
|
+
if (await exists(resolve(current, name))) return true;
|
|
416
|
+
const manifest = await readText(resolve(current, 'package.json'));
|
|
417
|
+
if (manifest !== null) {
|
|
418
|
+
try {
|
|
419
|
+
if (JSON.parse(manifest)?.prettier !== undefined) return true;
|
|
420
|
+
} catch {
|
|
421
|
+
// An unreadable ancestor manifest declares nothing here.
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
if (current === stop || dirname(current) === current) return false;
|
|
425
|
+
}
|
|
426
|
+
}
|
|
427
|
+
|
|
428
|
+
/**
|
|
429
|
+
* The shared accumulator every planning phase writes into: planned file
|
|
430
|
+
* actions, conflicts, managed hashes, and the resolution bookkeeping that
|
|
431
|
+
* `reconcileValue` / `addMapValues` read through `context`.
|
|
432
|
+
*/
|
|
433
|
+
function createPlanAccumulator({
|
|
434
|
+
root,
|
|
435
|
+
selected,
|
|
436
|
+
mode,
|
|
437
|
+
setupVersion,
|
|
438
|
+
resolutions,
|
|
439
|
+
requestedResolutions,
|
|
440
|
+
managedBefore,
|
|
441
|
+
}) {
|
|
442
|
+
const plan = {
|
|
443
|
+
root,
|
|
444
|
+
selected,
|
|
445
|
+
mode,
|
|
446
|
+
setupVersion,
|
|
447
|
+
resolutions,
|
|
448
|
+
requestedResolutions,
|
|
449
|
+
managedBefore,
|
|
450
|
+
conflicts: [],
|
|
451
|
+
actions: [],
|
|
452
|
+
generatedPaths: [],
|
|
453
|
+
managedAfter: {},
|
|
454
|
+
knownResolutionIds: new Set(),
|
|
455
|
+
activeConflictIds: new Set(),
|
|
456
|
+
activeProposalIds: new Set(),
|
|
457
|
+
};
|
|
458
|
+
plan.context = {
|
|
459
|
+
conflicts: plan.conflicts,
|
|
460
|
+
managedBefore,
|
|
461
|
+
managedAfter: plan.managedAfter,
|
|
462
|
+
resolutions,
|
|
463
|
+
knownResolutionIds: plan.knownResolutionIds,
|
|
464
|
+
activeConflictIds: plan.activeConflictIds,
|
|
465
|
+
activeProposalIds: plan.activeProposalIds,
|
|
466
|
+
};
|
|
467
|
+
plan.addAction = async (path, value, kind = 'write') => {
|
|
468
|
+
const before = await readText(path);
|
|
469
|
+
// KF-G54HNG: a JSON file whose values already match is left alone, so a
|
|
470
|
+
// project formatter's layout (short arrays on one line) is not undone
|
|
471
|
+
// and a rerun plans nothing.
|
|
472
|
+
if (
|
|
473
|
+
(kind === 'json' || kind === 'state') &&
|
|
474
|
+
before !== null &&
|
|
475
|
+
sameJson(before, value)
|
|
476
|
+
)
|
|
477
|
+
return;
|
|
478
|
+
if (before !== value)
|
|
479
|
+
plan.actions.push({
|
|
480
|
+
path: portable(root, path),
|
|
481
|
+
absolutePath: path,
|
|
482
|
+
before,
|
|
483
|
+
after: value,
|
|
484
|
+
kind,
|
|
485
|
+
});
|
|
486
|
+
};
|
|
487
|
+
return plan;
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
/** Conflicts when the running setup differs from the project's installed kerfjs. */
|
|
491
|
+
async function planKerfVersion(plan) {
|
|
492
|
+
const { selected, setupVersion, resolutions } = plan;
|
|
493
|
+
const projectKerfVersion = await installedVersion(
|
|
494
|
+
selected.directory,
|
|
495
|
+
'kerfjs',
|
|
496
|
+
);
|
|
497
|
+
plan.knownResolutionIds.add('kerfjs-version');
|
|
498
|
+
if (projectKerfVersion && projectKerfVersion !== setupVersion) {
|
|
499
|
+
plan.activeConflictIds.add('kerfjs-version');
|
|
500
|
+
if (!resolutions['kerfjs-version'])
|
|
501
|
+
plan.conflicts.push({
|
|
502
|
+
id: 'kerfjs-version',
|
|
503
|
+
message: `running setup ${setupVersion} differs from installed kerfjs ${projectKerfVersion}; rerun with kerfjs@${projectKerfVersion}, or choose keep to retain project declarations or kerf to update them`,
|
|
504
|
+
});
|
|
505
|
+
}
|
|
506
|
+
}
|
|
507
|
+
|
|
508
|
+
/** The canonical AI guidance files (skills, cursorrules) and shared-guidance imports. */
|
|
509
|
+
async function planAiFiles(plan, aiManifest, guidanceSource) {
|
|
510
|
+
const { root, mode, resolutions, managedAfter } = plan;
|
|
511
|
+
for (const file of aiManifest.files) {
|
|
512
|
+
if (file.name === 'ui-skill' && mode !== 'ui') continue;
|
|
513
|
+
if (
|
|
514
|
+
file.name === 'cursorrules' &&
|
|
515
|
+
!(await exists(resolve(root, '.cursor'))) &&
|
|
516
|
+
!(await exists(resolve(root, '.cursorrules')))
|
|
517
|
+
)
|
|
518
|
+
continue;
|
|
519
|
+
const destination = resolve(root, file.dest);
|
|
520
|
+
const bundled = await readFile(resolve(packageRoot, file.bundle), 'utf8');
|
|
521
|
+
if ((file.name === 'skill' || file.name === 'ui-skill') && guidanceSource) {
|
|
522
|
+
const sourcePath = resolve(root, guidanceSource);
|
|
523
|
+
const importPath = relative(dirname(destination), sourcePath).replaceAll(
|
|
524
|
+
'\\',
|
|
525
|
+
'/',
|
|
526
|
+
);
|
|
527
|
+
const shared =
|
|
528
|
+
file.name === 'ui-skill'
|
|
529
|
+
? `---\nname: kerf-ui\ndescription: Use shared workspace guidance and the installed @kerfjs/ui instructions.\n---\n\n@${importPath}\n\nIn the selected package, read \`node_modules/@kerfjs/ui/llms.txt\` first, then \`node_modules/@kerfjs/ui/ai/skill.md\` and the component references they name.\n`
|
|
530
|
+
: `---\nname: kerf-app\ndescription: Use the shared workspace guidance for Kerf application work.\n---\n\n@${importPath}\n`;
|
|
531
|
+
const current = await readText(destination);
|
|
532
|
+
plan.knownResolutionIds.add(file.dest);
|
|
533
|
+
if (current !== null && current !== shared && !resolutions[file.dest]) {
|
|
534
|
+
plan.activeConflictIds.add(file.dest);
|
|
535
|
+
plan.conflicts.push({
|
|
536
|
+
id: file.dest,
|
|
537
|
+
message: 'shared guidance import differs from existing skill',
|
|
538
|
+
});
|
|
539
|
+
} else if (
|
|
540
|
+
current === null ||
|
|
541
|
+
current === shared ||
|
|
542
|
+
resolutions[file.dest] === 'kerf'
|
|
543
|
+
) {
|
|
544
|
+
await plan.addAction(destination, shared, 'canonical');
|
|
545
|
+
managedAfter[file.dest] = { sha256: sha256(shared) };
|
|
546
|
+
} else {
|
|
547
|
+
plan.activeConflictIds.add(file.dest);
|
|
548
|
+
}
|
|
549
|
+
continue;
|
|
550
|
+
}
|
|
551
|
+
const merged = mergeCanonical(
|
|
552
|
+
await readText(destination),
|
|
553
|
+
bundled,
|
|
554
|
+
file.history ?? {},
|
|
555
|
+
file.version,
|
|
556
|
+
);
|
|
557
|
+
plan.knownResolutionIds.add(file.dest);
|
|
558
|
+
if (merged.conflict) {
|
|
559
|
+
plan.activeConflictIds.add(file.dest);
|
|
560
|
+
if (!resolutions[file.dest])
|
|
561
|
+
plan.conflicts.push({ id: file.dest, message: merged.conflict });
|
|
562
|
+
else if (resolutions[file.dest] === 'kerf') {
|
|
563
|
+
const local = splitCanonical((await readText(destination)) ?? '');
|
|
564
|
+
const replacement = local.error ? bundled : bundled + local.append;
|
|
565
|
+
await plan.addAction(destination, replacement, 'canonical');
|
|
566
|
+
managedAfter[file.dest] = { sha256: sha256(bundled) };
|
|
567
|
+
}
|
|
568
|
+
} else {
|
|
569
|
+
await plan.addAction(destination, merged.value, 'canonical');
|
|
570
|
+
managedAfter[file.dest] = {
|
|
571
|
+
sha256: sha256(splitCanonical(merged.value).canonical),
|
|
572
|
+
};
|
|
573
|
+
}
|
|
574
|
+
}
|
|
575
|
+
if (mode === 'ui') {
|
|
576
|
+
const content = `---\nname: kerf-ui-design-mock\ndescription: Plan and review rendered Kerf UI screen concepts before implementation, using the installed package's design-mock workflow.\n---\n\nRead the selected project's installed \`node_modules/@kerfjs/ui/ai/design-mock/SKILL.md\` and follow it. Resolve that path from the selected package in a workspace. Read the same installed package's \`llms.txt\` and \`ai/skill.md\` as directed there so the design uses its actual component version.\n`;
|
|
577
|
+
for (const provider of ['.claude', '.agents']) {
|
|
578
|
+
const path = `${provider}/skills/kerf-ui-design-mock/SKILL.md`;
|
|
579
|
+
const destination = resolve(root, path);
|
|
580
|
+
const current = await readText(destination);
|
|
581
|
+
plan.knownResolutionIds.add(path);
|
|
582
|
+
if (current !== null && current !== content && !resolutions[path]) {
|
|
583
|
+
plan.activeConflictIds.add(path);
|
|
584
|
+
plan.conflicts.push({
|
|
585
|
+
id: path,
|
|
586
|
+
message:
|
|
587
|
+
'design-mock skill entry differs from installed guidance pointer',
|
|
588
|
+
});
|
|
589
|
+
} else if (
|
|
590
|
+
current === null ||
|
|
591
|
+
current === content ||
|
|
592
|
+
resolutions[path] === 'kerf'
|
|
593
|
+
) {
|
|
594
|
+
await plan.addAction(destination, content, 'canonical');
|
|
595
|
+
managedAfter[path] = { sha256: sha256(content) };
|
|
596
|
+
} else {
|
|
597
|
+
plan.activeConflictIds.add(path);
|
|
598
|
+
}
|
|
599
|
+
}
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* The selected package's package.json: scripts, tool devDependencies, the
|
|
605
|
+
* kerfjs / @kerfjs/ui dependency reconciliation, and (UI) the component
|
|
606
|
+
* catalog configuration. Returns the next manifest plus the facts later
|
|
607
|
+
* phases share.
|
|
608
|
+
*/
|
|
609
|
+
async function planManifest(plan, priorPackageState, packageKey) {
|
|
610
|
+
const {
|
|
611
|
+
root,
|
|
612
|
+
selected,
|
|
613
|
+
mode,
|
|
614
|
+
setupVersion,
|
|
615
|
+
resolutions,
|
|
616
|
+
requestedResolutions,
|
|
617
|
+
managedBefore,
|
|
618
|
+
context,
|
|
619
|
+
} = plan;
|
|
620
|
+
const packagePath = resolve(selected.directory, 'package.json');
|
|
621
|
+
const nextManifest = JSON.parse(JSON.stringify(selected.manifest));
|
|
622
|
+
const freshUiApp =
|
|
623
|
+
mode === 'ui' &&
|
|
624
|
+
!(await exists(resolve(selected.directory, 'src'))) &&
|
|
625
|
+
!(await exists(resolve(selected.directory, 'index.html'))) &&
|
|
626
|
+
!(await exists(resolve(selected.directory, 'vite.config.mjs'))) &&
|
|
627
|
+
!(await exists(resolve(selected.directory, 'app')));
|
|
628
|
+
const scaffoldUiApp =
|
|
629
|
+
freshUiApp ||
|
|
630
|
+
Boolean(
|
|
631
|
+
priorPackageState.managed?.[
|
|
632
|
+
`${packageKey === '.' ? '' : `${packageKey}/`}src/app/main.tsx`
|
|
633
|
+
],
|
|
634
|
+
);
|
|
635
|
+
nextManifest.scripts ??= {};
|
|
636
|
+
nextManifest.devDependencies ??= {};
|
|
637
|
+
nextManifest.dependencies ??= {};
|
|
638
|
+
const packageDoctorConfig = resolve(
|
|
639
|
+
selected.directory,
|
|
640
|
+
'.kerf-ui-doctor.json',
|
|
641
|
+
);
|
|
642
|
+
const workspaceDoctorArgs =
|
|
643
|
+
selected.directory === root
|
|
644
|
+
? ''
|
|
645
|
+
: ` --root ${portable(selected.directory, root)} --package ${nextManifest.name}${
|
|
646
|
+
mode === 'ui' || (await exists(packageDoctorConfig))
|
|
647
|
+
? ` --config ${shellArg(portable(root, packageDoctorConfig))}`
|
|
648
|
+
: ''
|
|
649
|
+
}`;
|
|
650
|
+
addMapValues(
|
|
651
|
+
nextManifest.scripts,
|
|
652
|
+
mode === 'ui'
|
|
653
|
+
? {
|
|
654
|
+
lint: 'prettier --check . --ignore-unknown && eslint . --max-warnings 0',
|
|
655
|
+
typecheck: 'tsc --noEmit',
|
|
656
|
+
check: `prettier --check . --ignore-unknown && eslint . --max-warnings 0 && tsc --noEmit && kerf-component-catalog --check && kerf-ui-doctor --full${workspaceDoctorArgs}${scaffoldUiApp ? ' && node --test tests/structure.test.mjs && vite build' : ''}`,
|
|
657
|
+
'kerf:check': `prettier --check . --ignore-unknown && eslint . --max-warnings 0 && tsc --noEmit && kerf-component-catalog --check && kerf-ui-doctor --full${workspaceDoctorArgs}${scaffoldUiApp ? ' && node --test tests/structure.test.mjs && vite build' : ''}`,
|
|
658
|
+
'kerf:doctor': `kerf-ui-doctor --full${workspaceDoctorArgs}`,
|
|
659
|
+
'kerf:doctor:changed': `kerf-ui-doctor --changed${workspaceDoctorArgs}`,
|
|
660
|
+
'catalog:generate': 'kerf-component-catalog --write',
|
|
661
|
+
'catalog:check': 'kerf-component-catalog --check',
|
|
662
|
+
...(scaffoldUiApp
|
|
663
|
+
? {
|
|
664
|
+
dev: 'vite',
|
|
665
|
+
build: 'vite build',
|
|
666
|
+
'test:structure': 'node --test tests/structure.test.mjs',
|
|
667
|
+
}
|
|
668
|
+
: {}),
|
|
669
|
+
}
|
|
670
|
+
: { 'kerf:check': 'tsc --noEmit && eslint .' },
|
|
671
|
+
'package.json#scripts',
|
|
672
|
+
context,
|
|
673
|
+
);
|
|
674
|
+
addMapValues(
|
|
675
|
+
nextManifest.devDependencies,
|
|
676
|
+
{
|
|
677
|
+
'eslint-plugin-kerfjs': setupVersion,
|
|
678
|
+
'@typescript-eslint/parser': '^8.0.0',
|
|
679
|
+
eslint: '^9.0.0',
|
|
680
|
+
typescript: '^5.0.0 || ^6.0.0',
|
|
681
|
+
...(mode === 'ui' ? { 'create-kerf-component': setupVersion } : {}),
|
|
682
|
+
...(mode === 'ui'
|
|
683
|
+
? {
|
|
684
|
+
'@eslint/js': '^9.0.0',
|
|
685
|
+
'@stylistic/eslint-plugin': '^5.0.0',
|
|
686
|
+
'eslint-plugin-simple-import-sort': '^12.1.1',
|
|
687
|
+
prettier: '^3.0.0',
|
|
688
|
+
'typescript-eslint': '^8.65.0',
|
|
689
|
+
...(scaffoldUiApp ? { vite: '^7.0.0' } : {}),
|
|
690
|
+
}
|
|
691
|
+
: {}),
|
|
692
|
+
},
|
|
693
|
+
'package.json#devDependencies',
|
|
694
|
+
context,
|
|
695
|
+
);
|
|
696
|
+
const reconcileDependency = (name) => {
|
|
697
|
+
const section =
|
|
698
|
+
['dependencies', 'devDependencies', 'peerDependencies'].find(
|
|
699
|
+
(candidate) => name in (nextManifest[candidate] ?? {}),
|
|
700
|
+
) ?? 'dependencies';
|
|
701
|
+
nextManifest[section] ??= {};
|
|
702
|
+
const id = `package.json#${section}.${name}`;
|
|
703
|
+
if (
|
|
704
|
+
allowsVersion(nextManifest[section][name], setupVersion) &&
|
|
705
|
+
managedBefore[id]?.sha256 !== hashValue(nextManifest[section][name])
|
|
706
|
+
) {
|
|
707
|
+
plan.knownResolutionIds.add(id);
|
|
708
|
+
return;
|
|
709
|
+
}
|
|
710
|
+
const dependencyContext =
|
|
711
|
+
name === 'kerfjs' && resolutions['kerfjs-version']
|
|
712
|
+
? {
|
|
713
|
+
...context,
|
|
714
|
+
resolutions: {
|
|
715
|
+
...resolutions,
|
|
716
|
+
[id]: requestedResolutions[id] ?? resolutions['kerfjs-version'],
|
|
717
|
+
},
|
|
718
|
+
}
|
|
719
|
+
: context;
|
|
720
|
+
reconcileValue({
|
|
721
|
+
target: nextManifest[section],
|
|
722
|
+
key: name,
|
|
723
|
+
value: setupVersion,
|
|
724
|
+
id,
|
|
725
|
+
...dependencyContext,
|
|
726
|
+
});
|
|
727
|
+
};
|
|
728
|
+
reconcileDependency('kerfjs');
|
|
729
|
+
if (mode === 'ui') reconcileDependency('@kerfjs/ui');
|
|
730
|
+
if (mode === 'ui') {
|
|
731
|
+
reconcileValue({
|
|
732
|
+
target: nextManifest,
|
|
733
|
+
key: 'kerfComponentCatalog',
|
|
734
|
+
value: {
|
|
735
|
+
source: './kerf.components.json',
|
|
736
|
+
output: './component-composition.json',
|
|
737
|
+
},
|
|
738
|
+
id: 'package.json#kerfComponentCatalog',
|
|
739
|
+
...context,
|
|
740
|
+
});
|
|
741
|
+
for (const [key, configuredPath] of Object.entries(
|
|
742
|
+
nextManifest.kerfComponentCatalog ?? {},
|
|
743
|
+
))
|
|
744
|
+
if (
|
|
745
|
+
typeof configuredPath !== 'string' ||
|
|
746
|
+
!contained(
|
|
747
|
+
selected.directory,
|
|
748
|
+
resolve(selected.directory, configuredPath),
|
|
749
|
+
)
|
|
750
|
+
)
|
|
751
|
+
throw new Error(
|
|
752
|
+
`kerfComponentCatalog.${key} must stay inside the selected package.`,
|
|
753
|
+
);
|
|
754
|
+
}
|
|
755
|
+
await plan.addAction(packagePath, stableJson(nextManifest), 'json');
|
|
756
|
+
return { nextManifest, scaffoldUiApp, packageDoctorConfig };
|
|
757
|
+
}
|
|
758
|
+
|
|
759
|
+
/** tsconfig.json: create it, or merge the recommended compiler options as JSONC edits. */
|
|
760
|
+
async function planTsconfig(plan) {
|
|
761
|
+
const { selected, mode, resolutions, managedAfter, context } = plan;
|
|
762
|
+
const tsconfigPath = resolve(selected.directory, 'tsconfig.json');
|
|
763
|
+
const tsconfigSource = await readText(tsconfigPath);
|
|
764
|
+
const tsconfigRecommendations = {
|
|
765
|
+
target: 'ES2022',
|
|
766
|
+
module: 'ESNext',
|
|
767
|
+
moduleResolution: 'Bundler',
|
|
768
|
+
strict: true,
|
|
769
|
+
...(mode === 'ui' ? { noUncheckedIndexedAccess: true } : {}),
|
|
770
|
+
jsx: 'react-jsx',
|
|
771
|
+
jsxImportSource: 'kerfjs',
|
|
772
|
+
};
|
|
773
|
+
if (tsconfigSource === null) {
|
|
774
|
+
const tsconfig = { compilerOptions: {}, include: ['src'] };
|
|
775
|
+
addMapValues(
|
|
776
|
+
tsconfig.compilerOptions,
|
|
777
|
+
tsconfigRecommendations,
|
|
778
|
+
'tsconfig.json#compilerOptions',
|
|
779
|
+
context,
|
|
780
|
+
);
|
|
781
|
+
await plan.addAction(tsconfigPath, stableJson(tsconfig), 'json');
|
|
782
|
+
return;
|
|
783
|
+
}
|
|
784
|
+
const parsed = parseJsoncDocument(tsconfigSource, 'tsconfig.json');
|
|
785
|
+
const rootId = 'tsconfig.json';
|
|
786
|
+
if (parsed.root.type !== 'object') {
|
|
787
|
+
plan.knownResolutionIds.add(rootId);
|
|
788
|
+
plan.activeConflictIds.add(rootId);
|
|
789
|
+
if (!resolutions[rootId])
|
|
790
|
+
plan.conflicts.push({
|
|
791
|
+
id: rootId,
|
|
792
|
+
message: 'root value must be an object',
|
|
793
|
+
});
|
|
794
|
+
else if (resolutions[rootId] === 'kerf') {
|
|
795
|
+
const replacement = {
|
|
796
|
+
compilerOptions: { ...tsconfigRecommendations },
|
|
797
|
+
include: ['src'],
|
|
798
|
+
};
|
|
799
|
+
for (const [key, value] of Object.entries(tsconfigRecommendations))
|
|
800
|
+
managedAfter[`tsconfig.json#compilerOptions.${key}`] = {
|
|
801
|
+
sha256: hashValue(value),
|
|
802
|
+
};
|
|
803
|
+
await plan.addAction(tsconfigPath, stableJson(replacement), 'json');
|
|
804
|
+
}
|
|
805
|
+
return;
|
|
806
|
+
}
|
|
807
|
+
const edits = [];
|
|
808
|
+
const rootInsertions = [];
|
|
809
|
+
const compilerProperty = parsed.root.properties.get('compilerOptions');
|
|
810
|
+
if (compilerProperty && compilerProperty.valueNode.type !== 'object') {
|
|
811
|
+
const id = 'tsconfig.json#compilerOptions';
|
|
812
|
+
plan.knownResolutionIds.add(id);
|
|
813
|
+
plan.activeConflictIds.add(id);
|
|
814
|
+
if (!resolutions[id])
|
|
815
|
+
plan.conflicts.push({ id, message: 'existing value must be an object' });
|
|
816
|
+
else if (resolutions[id] === 'kerf') {
|
|
817
|
+
edits.push(
|
|
818
|
+
jsoncValueEdit(
|
|
819
|
+
compilerProperty.valueNode,
|
|
820
|
+
tsconfigRecommendations,
|
|
821
|
+
tsconfigSource,
|
|
822
|
+
),
|
|
823
|
+
);
|
|
824
|
+
for (const [key, value] of Object.entries(tsconfigRecommendations))
|
|
825
|
+
managedAfter[`tsconfig.json#compilerOptions.${key}`] = {
|
|
826
|
+
sha256: hashValue(value),
|
|
827
|
+
};
|
|
828
|
+
}
|
|
829
|
+
} else {
|
|
830
|
+
const compilerOptions = compilerProperty?.valueNode.value ?? {};
|
|
831
|
+
const before = { ...compilerOptions };
|
|
832
|
+
addMapValues(
|
|
833
|
+
compilerOptions,
|
|
834
|
+
tsconfigRecommendations,
|
|
835
|
+
'tsconfig.json#compilerOptions',
|
|
836
|
+
context,
|
|
837
|
+
);
|
|
838
|
+
if (compilerProperty) {
|
|
839
|
+
const missing = [];
|
|
840
|
+
for (const [key, value] of Object.entries(compilerOptions)) {
|
|
841
|
+
const property = compilerProperty.valueNode.properties.get(key);
|
|
842
|
+
if (!property) missing.push([key, value]);
|
|
843
|
+
else if (before[key] !== value)
|
|
844
|
+
edits.push(jsoncValueEdit(property.valueNode, value, tsconfigSource));
|
|
845
|
+
}
|
|
846
|
+
edits.push(
|
|
847
|
+
...jsoncInsertProperties(
|
|
848
|
+
tsconfigSource,
|
|
849
|
+
compilerProperty.valueNode,
|
|
850
|
+
missing,
|
|
851
|
+
),
|
|
852
|
+
);
|
|
853
|
+
} else {
|
|
854
|
+
rootInsertions.push(['compilerOptions', compilerOptions]);
|
|
855
|
+
}
|
|
856
|
+
}
|
|
857
|
+
if (!parsed.root.properties.has('include'))
|
|
858
|
+
rootInsertions.push(['include', ['src']]);
|
|
859
|
+
edits.push(
|
|
860
|
+
...jsoncInsertProperties(tsconfigSource, parsed.root, rootInsertions),
|
|
861
|
+
);
|
|
862
|
+
await plan.addAction(
|
|
863
|
+
tsconfigPath,
|
|
864
|
+
applyJsoncEdits(tsconfigSource, edits),
|
|
865
|
+
'jsonc',
|
|
866
|
+
);
|
|
867
|
+
}
|
|
868
|
+
|
|
869
|
+
/** The ESLint flat config: generate one, or merge / conflict on an existing one. */
|
|
870
|
+
async function planEslint(plan, nextManifest) {
|
|
871
|
+
const { root, selected, mode, resolutions, managedBefore, managedAfter } =
|
|
872
|
+
plan;
|
|
873
|
+
const eslintNames = [
|
|
874
|
+
'eslint.config.js',
|
|
875
|
+
'eslint.config.mjs',
|
|
876
|
+
'eslint.config.cjs',
|
|
877
|
+
];
|
|
878
|
+
let eslintPath;
|
|
879
|
+
for (const name of eslintNames)
|
|
880
|
+
if (await exists(resolve(selected.directory, name))) {
|
|
881
|
+
eslintPath = resolve(selected.directory, name);
|
|
882
|
+
break;
|
|
883
|
+
}
|
|
884
|
+
if (!eslintPath) {
|
|
885
|
+
const generatedPath = resolve(selected.directory, 'eslint.config.mjs');
|
|
886
|
+
const generated = eslintTemplate(mode);
|
|
887
|
+
await plan.addAction(generatedPath, generated);
|
|
888
|
+
managedAfter[portable(root, generatedPath)] = { sha256: sha256(generated) };
|
|
889
|
+
return;
|
|
890
|
+
}
|
|
891
|
+
const source = await readText(eslintPath);
|
|
892
|
+
const id = portable(root, eslintPath);
|
|
893
|
+
plan.knownResolutionIds.add(id);
|
|
894
|
+
const commonjs =
|
|
895
|
+
eslintPath.endsWith('.cjs') ||
|
|
896
|
+
(eslintPath.endsWith('.js') && nextManifest.type !== 'module');
|
|
897
|
+
const template = eslintTemplate(mode, commonjs ? 'commonjs' : 'module');
|
|
898
|
+
const wasManaged = managedBefore[id]?.sha256 === sha256(source);
|
|
899
|
+
const wasEditedManaged = Boolean(managedBefore[id]) && !wasManaged;
|
|
900
|
+
const merged = wasManaged
|
|
901
|
+
? { value: template }
|
|
902
|
+
: wasEditedManaged
|
|
903
|
+
? { conflict: 'setup-authored config was customized' }
|
|
904
|
+
: mode === 'ui'
|
|
905
|
+
? source === template
|
|
906
|
+
? { value: source }
|
|
907
|
+
: {
|
|
908
|
+
conflict:
|
|
909
|
+
'existing UI ESLint config needs the full typed Kerf baseline',
|
|
910
|
+
}
|
|
911
|
+
: commonjs
|
|
912
|
+
? {
|
|
913
|
+
conflict:
|
|
914
|
+
'CommonJS config requires an explicit Kerf preset merge',
|
|
915
|
+
}
|
|
916
|
+
: mergeEslintConfig(source, mode);
|
|
917
|
+
if (merged.conflict) {
|
|
918
|
+
plan.activeConflictIds.add(id);
|
|
919
|
+
if (!resolutions[id])
|
|
920
|
+
plan.conflicts.push({
|
|
921
|
+
id,
|
|
922
|
+
message: `${merged.conflict}; choose keep or kerf`,
|
|
923
|
+
});
|
|
924
|
+
else if (resolutions[id] === 'kerf') {
|
|
925
|
+
const generated = template;
|
|
926
|
+
await plan.addAction(eslintPath, generated);
|
|
927
|
+
managedAfter[id] = { sha256: sha256(generated) };
|
|
928
|
+
}
|
|
929
|
+
} else {
|
|
930
|
+
await plan.addAction(eslintPath, merged.value);
|
|
931
|
+
if (wasManaged) managedAfter[id] = { sha256: sha256(merged.value) };
|
|
932
|
+
}
|
|
933
|
+
}
|
|
934
|
+
|
|
935
|
+
/** UI mode: Prettier config, doctor config, and the fresh-app scaffold files. */
|
|
936
|
+
async function planUiBaseline(plan, { scaffoldUiApp, packageDoctorConfig }) {
|
|
937
|
+
const { root, selected, resolutions, managedBefore, managedAfter } = plan;
|
|
938
|
+
// A proposal the project can decline with `prettier.config.mjs=skip`
|
|
939
|
+
// (package-relative path as its id), remembered with the other
|
|
940
|
+
// resolutions so a deleted config is not proposed again.
|
|
941
|
+
if (!(await prettierConfigApplies(root, selected.directory))) {
|
|
942
|
+
const destination = resolve(selected.directory, 'prettier.config.mjs');
|
|
943
|
+
const id = portable(root, destination);
|
|
944
|
+
plan.knownResolutionIds.add(id);
|
|
945
|
+
plan.activeProposalIds.add(id);
|
|
946
|
+
if (resolutions[id] !== 'skip')
|
|
947
|
+
await plan.addAction(destination, uiPrettierConfig);
|
|
948
|
+
}
|
|
949
|
+
if (!(await exists(packageDoctorConfig)))
|
|
950
|
+
await plan.addAction(
|
|
951
|
+
packageDoctorConfig,
|
|
952
|
+
stableJson(uiDoctorConfig),
|
|
953
|
+
'json',
|
|
954
|
+
);
|
|
955
|
+
if (!scaffoldUiApp) return;
|
|
956
|
+
for (const [path, content] of Object.entries(uiAppFiles())) {
|
|
957
|
+
const destination = resolve(selected.directory, path);
|
|
958
|
+
const id = portable(root, destination);
|
|
959
|
+
const current = await readText(destination);
|
|
960
|
+
plan.knownResolutionIds.add(id);
|
|
961
|
+
if (
|
|
962
|
+
current !== null &&
|
|
963
|
+
current !== content &&
|
|
964
|
+
managedBefore[id]?.sha256 !== sha256(current)
|
|
965
|
+
) {
|
|
966
|
+
plan.activeConflictIds.add(id);
|
|
967
|
+
if (!resolutions[id]) {
|
|
968
|
+
plan.conflicts.push({
|
|
969
|
+
id,
|
|
970
|
+
message: 'app scaffold file was customized; choose keep or kerf',
|
|
971
|
+
});
|
|
972
|
+
continue;
|
|
973
|
+
}
|
|
974
|
+
if (resolutions[id] === 'keep') continue;
|
|
975
|
+
}
|
|
976
|
+
await plan.addAction(destination, content);
|
|
977
|
+
managedAfter[id] = { sha256: sha256(content) };
|
|
978
|
+
}
|
|
979
|
+
}
|
|
980
|
+
|
|
981
|
+
/**
|
|
982
|
+
* UI mode with a component catalog: the workspace .kerf-ui-profile.json
|
|
983
|
+
* catalog entry, the catalog metadata source, and the generated catalog paths.
|
|
984
|
+
*/
|
|
985
|
+
async function planUiCatalog(plan, nextManifest) {
|
|
986
|
+
const { root, selected, context } = plan;
|
|
987
|
+
const profilePath = resolve(root, '.kerf-ui-profile.json');
|
|
988
|
+
const currentProfileSource = await readText(profilePath);
|
|
989
|
+
const currentProfile =
|
|
990
|
+
currentProfileSource === null
|
|
991
|
+
? undefined
|
|
992
|
+
: parseJsonFile(currentProfileSource, profilePath, root);
|
|
993
|
+
const profileCatalogPath = (configuredPath) => {
|
|
994
|
+
const relative = portable(
|
|
995
|
+
root,
|
|
996
|
+
resolve(selected.directory, configuredPath),
|
|
997
|
+
);
|
|
998
|
+
return relative.startsWith('.') ? relative : `./${relative}`;
|
|
999
|
+
};
|
|
1000
|
+
const profile = mergeProfile(
|
|
1001
|
+
currentProfile,
|
|
1002
|
+
profileTemplate(
|
|
1003
|
+
nextManifest.name,
|
|
1004
|
+
profileCatalogPath(nextManifest.kerfComponentCatalog.output),
|
|
1005
|
+
nextManifest.kerfComponentCatalog.selectionOutput
|
|
1006
|
+
? profileCatalogPath(nextManifest.kerfComponentCatalog.selectionOutput)
|
|
1007
|
+
: undefined,
|
|
1008
|
+
),
|
|
1009
|
+
context,
|
|
1010
|
+
);
|
|
1011
|
+
await plan.addAction(profilePath, stableJson(profile), 'json');
|
|
1012
|
+
const metadataPath = resolve(
|
|
1013
|
+
selected.directory,
|
|
1014
|
+
nextManifest.kerfComponentCatalog.source,
|
|
1015
|
+
);
|
|
1016
|
+
if (nextManifest.kerfComponentCatalog.selectionOutput) {
|
|
1017
|
+
const metadata = await readJson(metadataPath, root);
|
|
1018
|
+
if (
|
|
1019
|
+
!metadata ||
|
|
1020
|
+
typeof metadata.description !== 'string' ||
|
|
1021
|
+
!metadata.description.trim()
|
|
1022
|
+
)
|
|
1023
|
+
throw new Error(
|
|
1024
|
+
`${portable(root, metadataPath)}: selectionOutput requires an authored metadata source with a nonempty description. Add the source and description before running setup.`,
|
|
1025
|
+
);
|
|
1026
|
+
} else if (!(await exists(metadataPath)))
|
|
1027
|
+
await plan.addAction(metadataPath, stableJson(metadataTemplate()), 'json');
|
|
1028
|
+
if (
|
|
1029
|
+
nextManifest.scripts['catalog:generate'] &&
|
|
1030
|
+
dependencies(nextManifest)['create-kerf-component']
|
|
1031
|
+
) {
|
|
1032
|
+
plan.generatedPaths.push(
|
|
1033
|
+
resolve(selected.directory, nextManifest.kerfComponentCatalog.output),
|
|
1034
|
+
);
|
|
1035
|
+
if (nextManifest.kerfComponentCatalog.selectionOutput)
|
|
1036
|
+
plan.generatedPaths.push(
|
|
1037
|
+
resolve(
|
|
1038
|
+
selected.directory,
|
|
1039
|
+
nextManifest.kerfComponentCatalog.selectionOutput,
|
|
1040
|
+
),
|
|
1041
|
+
);
|
|
1042
|
+
}
|
|
1043
|
+
}
|
|
1044
|
+
|
|
1045
|
+
/** Every requested resolution must name a live conflict or proposal. */
|
|
1046
|
+
function validateRequestedResolutions(plan) {
|
|
1047
|
+
for (const [id, resolution] of Object.entries(plan.requestedResolutions)) {
|
|
1048
|
+
if (!['keep', 'kerf', 'skip'].includes(resolution))
|
|
1049
|
+
throw new Error(`Resolution ${id} must be keep, kerf, or skip.`);
|
|
1050
|
+
if (!plan.knownResolutionIds.has(id))
|
|
1051
|
+
throw new Error(`Unknown resolution id ${id}.`);
|
|
1052
|
+
if (resolution === 'skip' && plan.activeConflictIds.has(id))
|
|
1053
|
+
throw new Error(
|
|
1054
|
+
`Resolution ${id} cannot skip a conflict; choose keep or kerf.`,
|
|
1055
|
+
);
|
|
1056
|
+
if (
|
|
1057
|
+
!plan.activeConflictIds.has(id) &&
|
|
1058
|
+
!(resolution !== 'keep' && plan.activeProposalIds.has(id))
|
|
1059
|
+
)
|
|
1060
|
+
throw new Error(
|
|
1061
|
+
`Stale resolution id ${id}; there is no applicable conflict or proposal.`,
|
|
1062
|
+
);
|
|
1063
|
+
}
|
|
1064
|
+
}
|
|
1065
|
+
|
|
1066
|
+
/** The next .kerf-ai-setup.json: prior package states plus this package's. */
|
|
1067
|
+
function nextSetupState(plan, { manager, priorState, packageEntry }) {
|
|
1068
|
+
return {
|
|
1069
|
+
schemaVersion: 2,
|
|
1070
|
+
setupVersion: plan.setupVersion,
|
|
1071
|
+
packageManager: manager.name,
|
|
1072
|
+
...(manager.version ? { packageManagerVersion: manager.version } : {}),
|
|
1073
|
+
...(manager.variant ? { packageManagerVariant: manager.variant } : {}),
|
|
1074
|
+
packages: {
|
|
1075
|
+
...(priorState.packages ??
|
|
1076
|
+
(priorState.packagePath
|
|
1077
|
+
? {
|
|
1078
|
+
[priorState.packagePath]: {
|
|
1079
|
+
mode: priorState.mode,
|
|
1080
|
+
package: priorState.package,
|
|
1081
|
+
packagePath: priorState.packagePath,
|
|
1082
|
+
...(priorState.guidanceSource
|
|
1083
|
+
? { guidanceSource: priorState.guidanceSource }
|
|
1084
|
+
: {}),
|
|
1085
|
+
managed: priorState.managed ?? {},
|
|
1086
|
+
resolutions: priorState.resolutions ?? {},
|
|
1087
|
+
},
|
|
1088
|
+
}
|
|
1089
|
+
: {})),
|
|
1090
|
+
[packageEntry.packagePath]: packageEntry,
|
|
1091
|
+
},
|
|
1092
|
+
};
|
|
1093
|
+
}
|
|
1094
|
+
|
|
1095
|
+
export async function planKerfSetup({
|
|
1096
|
+
root = process.cwd(),
|
|
1097
|
+
package: selector,
|
|
1098
|
+
mode: requestedMode,
|
|
1099
|
+
version,
|
|
1100
|
+
resolutions = {},
|
|
1101
|
+
guidanceSource,
|
|
1102
|
+
} = {}) {
|
|
1103
|
+
root = resolve(root);
|
|
1104
|
+
const selected = await selectPackage(root, selector, requestedMode);
|
|
1105
|
+
const detectedMode = await detectMode(selected);
|
|
1106
|
+
const mode = requestedMode ?? detectedMode;
|
|
1107
|
+
if (!mode) throw new Error('Pass --core or --ui for a new Kerf package.');
|
|
1108
|
+
if (requestedMode && detectedMode && requestedMode !== detectedMode)
|
|
1109
|
+
throw new Error(
|
|
1110
|
+
`Requested ${requestedMode} conflicts with detected ${detectedMode} usage.`,
|
|
1111
|
+
);
|
|
1112
|
+
const ownManifest = await readJson(resolve(packageRoot, 'package.json'));
|
|
1113
|
+
const setupVersion = version ?? ownManifest.version;
|
|
1114
|
+
const statePath = resolve(root, '.kerf-ai-setup.json');
|
|
1115
|
+
const priorState = (await readJson(statePath, root)) ?? {};
|
|
1116
|
+
if (Object.keys(priorState).length) validateSetupState(priorState);
|
|
1117
|
+
const packageKey = portable(root, selected.directory);
|
|
1118
|
+
const legacyPackageState =
|
|
1119
|
+
priorState.packagePath === packageKey ? priorState : {};
|
|
1120
|
+
const priorPackageState =
|
|
1121
|
+
priorState.packages?.[packageKey] ?? legacyPackageState;
|
|
1122
|
+
guidanceSource = await validatedGuidanceSource(
|
|
1123
|
+
root,
|
|
1124
|
+
guidanceSource ?? priorPackageState.guidanceSource,
|
|
1125
|
+
);
|
|
1126
|
+
if (
|
|
1127
|
+
priorPackageState.package &&
|
|
1128
|
+
priorPackageState.package !== (selected.manifest.name ?? packageKey)
|
|
1129
|
+
)
|
|
1130
|
+
throw new Error(`Setup state package identity changed at ${packageKey}.`);
|
|
1131
|
+
|
|
1132
|
+
const plan = createPlanAccumulator({
|
|
1133
|
+
root,
|
|
1134
|
+
selected,
|
|
1135
|
+
mode,
|
|
1136
|
+
setupVersion,
|
|
1137
|
+
requestedResolutions: { ...resolutions },
|
|
1138
|
+
resolutions: { ...(priorPackageState.resolutions ?? {}), ...resolutions },
|
|
1139
|
+
managedBefore: priorPackageState.managed ?? {},
|
|
1140
|
+
});
|
|
1141
|
+
const aiManifest = await readJson(resolve(packageRoot, 'ai/manifest.json'));
|
|
1142
|
+
await planKerfVersion(plan);
|
|
1143
|
+
await planAiFiles(plan, aiManifest, guidanceSource);
|
|
1144
|
+
const manifestPlan = await planManifest(plan, priorPackageState, packageKey);
|
|
1145
|
+
const { nextManifest } = manifestPlan;
|
|
1146
|
+
await planTsconfig(plan);
|
|
1147
|
+
await planEslint(plan, nextManifest);
|
|
1148
|
+
if (mode === 'ui') {
|
|
1149
|
+
await planUiBaseline(plan, manifestPlan);
|
|
1150
|
+
if (!nextManifest.name)
|
|
1151
|
+
throw new Error(
|
|
1152
|
+
'UI setup requires package.json name for catalog identity.',
|
|
1153
|
+
);
|
|
1154
|
+
if (nextManifest.kerfComponentCatalog !== undefined)
|
|
1155
|
+
await planUiCatalog(plan, nextManifest);
|
|
1156
|
+
}
|
|
1157
|
+
validateRequestedResolutions(plan);
|
|
1158
|
+
|
|
1159
|
+
const {
|
|
1160
|
+
resolutions: effectiveResolutions,
|
|
1161
|
+
activeConflictIds,
|
|
1162
|
+
activeProposalIds,
|
|
1163
|
+
} = plan;
|
|
1164
|
+
const manager = await packageManagerInfo(root);
|
|
1165
|
+
const state = nextSetupState(plan, {
|
|
1166
|
+
manager,
|
|
1167
|
+
priorState,
|
|
1168
|
+
packageEntry: {
|
|
1169
|
+
mode,
|
|
1170
|
+
package: nextManifest.name ?? packageKey,
|
|
1171
|
+
packagePath: packageKey,
|
|
1172
|
+
...(guidanceSource ? { guidanceSource } : {}),
|
|
1173
|
+
managed: plan.managedAfter,
|
|
1174
|
+
resolutions: Object.fromEntries(
|
|
1175
|
+
[...new Set([...activeConflictIds, ...activeProposalIds])]
|
|
1176
|
+
.filter(
|
|
1177
|
+
(id) =>
|
|
1178
|
+
(activeConflictIds.has(id) &&
|
|
1179
|
+
effectiveResolutions[id] === 'keep') ||
|
|
1180
|
+
(activeProposalIds.has(id) &&
|
|
1181
|
+
effectiveResolutions[id] === 'skip'),
|
|
1182
|
+
)
|
|
1183
|
+
.map((id) => [id, effectiveResolutions[id]]),
|
|
1184
|
+
),
|
|
1185
|
+
},
|
|
1186
|
+
});
|
|
1187
|
+
await plan.addAction(statePath, stableJson(state), 'state');
|
|
1188
|
+
return {
|
|
1189
|
+
schemaVersion: 1,
|
|
1190
|
+
root,
|
|
1191
|
+
packageRoot: selected.directory,
|
|
1192
|
+
packageName: nextManifest.name ?? packageKey,
|
|
1193
|
+
packageManager: state.packageManager,
|
|
1194
|
+
packageManagerVersion: manager.version,
|
|
1195
|
+
packageManagerVariant: manager.variant,
|
|
1196
|
+
mode,
|
|
1197
|
+
setupVersion,
|
|
1198
|
+
actions: plan.actions,
|
|
1199
|
+
proposalIds: [...activeProposalIds].filter(
|
|
1200
|
+
(id) => effectiveResolutions[id] !== 'skip',
|
|
1201
|
+
),
|
|
1202
|
+
conflicts: plan.conflicts,
|
|
1203
|
+
generatedPaths: plan.generatedPaths,
|
|
1204
|
+
};
|
|
1205
|
+
}
|
|
1206
|
+
|
|
1207
|
+
export function formatSetupPlan(plan) {
|
|
1208
|
+
const lines = [
|
|
1209
|
+
`Kerf AI setup: ${plan.mode} package ${portable(plan.root, plan.packageRoot)}`,
|
|
1210
|
+
];
|
|
1211
|
+
let shown = 0;
|
|
1212
|
+
const render = (key, value) =>
|
|
1213
|
+
/token|secret|password|credential/i.test(key)
|
|
1214
|
+
? '<redacted>'
|
|
1215
|
+
: value === undefined
|
|
1216
|
+
? '<missing>'
|
|
1217
|
+
: redactText(JSON.stringify(value));
|
|
1218
|
+
const leaves = (value, prefix = '$', output = new Map()) => {
|
|
1219
|
+
if (value && typeof value === 'object') {
|
|
1220
|
+
for (const [key, child] of Object.entries(value))
|
|
1221
|
+
leaves(
|
|
1222
|
+
child,
|
|
1223
|
+
Array.isArray(value) ? `${prefix}[${key}]` : `${prefix}.${key}`,
|
|
1224
|
+
output,
|
|
1225
|
+
);
|
|
1226
|
+
} else output.set(prefix, value);
|
|
1227
|
+
return output;
|
|
1228
|
+
};
|
|
1229
|
+
for (const action of plan.actions) {
|
|
1230
|
+
lines.push(
|
|
1231
|
+
`${action.before === null ? 'CREATE' : 'UPDATE'} ${action.path}`,
|
|
1232
|
+
);
|
|
1233
|
+
if (shown >= 120) continue;
|
|
1234
|
+
if (
|
|
1235
|
+
action.kind === 'json' ||
|
|
1236
|
+
action.kind === 'jsonc' ||
|
|
1237
|
+
action.kind === 'state'
|
|
1238
|
+
) {
|
|
1239
|
+
const before = leaves(
|
|
1240
|
+
action.before === null
|
|
1241
|
+
? {}
|
|
1242
|
+
: action.kind === 'jsonc'
|
|
1243
|
+
? parseJsoncDocument(action.before, action.path).value
|
|
1244
|
+
: JSON.parse(action.before),
|
|
1245
|
+
);
|
|
1246
|
+
const after = leaves(
|
|
1247
|
+
action.kind === 'jsonc'
|
|
1248
|
+
? parseJsoncDocument(action.after, action.path).value
|
|
1249
|
+
: JSON.parse(action.after),
|
|
1250
|
+
);
|
|
1251
|
+
const keys = new Set([...before.keys(), ...after.keys()]);
|
|
1252
|
+
for (const key of keys) {
|
|
1253
|
+
if (action.kind === 'state' && key.includes('.managed.')) continue;
|
|
1254
|
+
if (JSON.stringify(before.get(key)) === JSON.stringify(after.get(key)))
|
|
1255
|
+
continue;
|
|
1256
|
+
if (shown++ >= 120) break;
|
|
1257
|
+
lines.push(
|
|
1258
|
+
` ${key}: ${render(key, before.get(key))} -> ${render(key, after.get(key))}`,
|
|
1259
|
+
);
|
|
1260
|
+
}
|
|
1261
|
+
} else {
|
|
1262
|
+
const beforeLines = action.before?.split('\n').length ?? 0;
|
|
1263
|
+
const afterLines = action.after.split('\n').length;
|
|
1264
|
+
lines.push(` content: ${beforeLines} line(s) -> ${afterLines} line(s)`);
|
|
1265
|
+
shown += 1;
|
|
1266
|
+
}
|
|
1267
|
+
}
|
|
1268
|
+
if (shown >= 120) lines.push(' … additional changes omitted');
|
|
1269
|
+
for (const conflict of plan.conflicts)
|
|
1270
|
+
lines.push(
|
|
1271
|
+
`CONFLICT ${conflict.id}: ${conflict.message} (use --resolve ${conflict.id}=keep|kerf)`,
|
|
1272
|
+
);
|
|
1273
|
+
for (const id of plan.proposalIds ?? [])
|
|
1274
|
+
lines.push(`PROPOSAL ${id} (use --resolve ${id}=skip to decline)`);
|
|
1275
|
+
if (!plan.actions.length && !plan.conflicts.length) lines.push('No changes.');
|
|
1276
|
+
lines.push('AI guidance: .claude/skills/kerf-app/SKILL.md');
|
|
1277
|
+
if (plan.mode === 'ui') {
|
|
1278
|
+
lines.push('AI UI guidance: .claude/skills/kerf-ui/SKILL.md');
|
|
1279
|
+
lines.push(
|
|
1280
|
+
'AI design mocks: .claude/skills/kerf-ui-design-mock/SKILL.md and .agents/skills/kerf-ui-design-mock/SKILL.md',
|
|
1281
|
+
);
|
|
1282
|
+
lines.push(
|
|
1283
|
+
`Read first: ${portable(plan.root, resolve(plan.packageRoot, 'node_modules/@kerfjs/ui/llms.txt'))}`,
|
|
1284
|
+
);
|
|
1285
|
+
lines.push(
|
|
1286
|
+
`Then read: ${portable(plan.root, resolve(plan.packageRoot, 'node_modules/@kerfjs/ui/ai/skill.md'))}`,
|
|
1287
|
+
);
|
|
1288
|
+
}
|
|
1289
|
+
return lines.join('\n');
|
|
1290
|
+
}
|