@hanna84/mcp-writing 2.12.4 → 2.12.6
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 +20 -0
- package/async-jobs.js +1 -218
- package/async-progress.js +1 -1
- package/helpers.js +2 -2
- package/importer.js +1 -448
- package/index.js +1 -501
- package/metadata-lint.js +1 -468
- package/package.json +32 -2
- package/runtime-diagnostics.js +1 -97
- package/scene-character-batch.js +1 -246
- package/scene-character-normalization.js +1 -199
- package/scripts/async-job-runner.mjs +3 -3
- package/scripts/generate-tool-docs.mjs +21 -3
- package/scripts/import.js +1 -1
- package/scripts/lint-metadata.mjs +1 -1
- package/scripts/manual-scrivener-realtest.mjs +3 -3
- package/scripts/merge-scrivx.js +2 -2
- package/scripts/new-world-entity.js +2 -2
- package/scripts/normalize-scene-characters.mjs +3 -3
- package/scripts/profile-review-bundles.mjs +1 -1
- package/scrivener-direct.js +1 -843
- package/src/index.js +502 -0
- package/src/runtime/async-jobs.js +218 -0
- package/src/runtime/async-progress.js +1 -0
- package/src/runtime/runtime-diagnostics.js +97 -0
- package/src/sync/importer.js +448 -0
- package/src/sync/metadata-lint.js +468 -0
- package/src/sync/scene-character-batch.js +246 -0
- package/src/sync/scene-character-normalization.js +199 -0
- package/src/sync/scrivener-direct.js +843 -0
- package/src/sync/sync.js +755 -0
- package/src/world/world-entity-templates.js +116 -0
- package/sync.js +1 -755
- package/tools/editing.js +1 -1
- package/tools/metadata.js +2 -2
- package/tools/review-bundles.js +1 -1
- package/tools/styleguide.js +1 -1
- package/tools/sync.js +2 -2
- package/world-entity-templates.js +1 -116
package/metadata-lint.js
CHANGED
|
@@ -1,468 +1 @@
|
|
|
1
|
-
|
|
2
|
-
import path from "node:path";
|
|
3
|
-
import { z } from "zod";
|
|
4
|
-
import {
|
|
5
|
-
inferProjectAndUniverse,
|
|
6
|
-
isCanonicalWorldEntityFile,
|
|
7
|
-
isWorldFile,
|
|
8
|
-
parseFile,
|
|
9
|
-
sidecarPath,
|
|
10
|
-
walkFiles,
|
|
11
|
-
walkSidecars,
|
|
12
|
-
worldEntityFolderKey,
|
|
13
|
-
worldEntityKindForPath,
|
|
14
|
-
} from "./sync.js";
|
|
15
|
-
import yaml from "js-yaml";
|
|
16
|
-
|
|
17
|
-
const { load: parseYaml } = yaml;
|
|
18
|
-
|
|
19
|
-
const metadataKindSchema = z.enum(["scene", "character", "place"]);
|
|
20
|
-
|
|
21
|
-
const threadLinkSchema = z.object({
|
|
22
|
-
thread_id: z.string().min(1),
|
|
23
|
-
beat: z.string().min(1).optional(),
|
|
24
|
-
thread_name: z.string().min(1).optional(),
|
|
25
|
-
status: z.string().min(1).optional(),
|
|
26
|
-
});
|
|
27
|
-
|
|
28
|
-
const sceneSchema = z.object({
|
|
29
|
-
scene_id: z.string().min(1),
|
|
30
|
-
external_source: z.string().min(1).optional(),
|
|
31
|
-
external_id: z.string().min(1).optional(),
|
|
32
|
-
title: z.string().min(1).optional(),
|
|
33
|
-
part: z.number().int().positive().optional(),
|
|
34
|
-
chapter: z.number().int().positive().optional(),
|
|
35
|
-
chapter_title: z.string().min(1).optional(),
|
|
36
|
-
pov: z.string().min(1).optional(),
|
|
37
|
-
logline: z.string().min(1).optional(),
|
|
38
|
-
save_the_cat_beat: z.string().min(1).optional(),
|
|
39
|
-
status: z.string().min(1).optional(),
|
|
40
|
-
timeline_position: z.number().int().optional(),
|
|
41
|
-
story_time: z.string().min(1).optional(),
|
|
42
|
-
word_count: z.number().int().nonnegative().optional(),
|
|
43
|
-
scene_change: z.string().min(1).optional(),
|
|
44
|
-
causality: z.string().min(1).optional(),
|
|
45
|
-
stakes: z.string().min(1).optional(),
|
|
46
|
-
scene_functions: z.array(z.string().min(1)).optional(),
|
|
47
|
-
characters: z.array(z.string().min(1)).optional(),
|
|
48
|
-
places: z.array(z.string().min(1)).optional(),
|
|
49
|
-
tags: z.array(z.string().min(1)).optional(),
|
|
50
|
-
versions: z.array(z.string().min(1)).optional(),
|
|
51
|
-
threads: z.array(threadLinkSchema).optional(),
|
|
52
|
-
});
|
|
53
|
-
|
|
54
|
-
const characterSchema = z.object({
|
|
55
|
-
character_id: z.string().min(1),
|
|
56
|
-
canonical: z.boolean().optional(),
|
|
57
|
-
name: z.string().min(1).optional(),
|
|
58
|
-
role: z.string().min(1).optional(),
|
|
59
|
-
group: z.string().min(1).optional(),
|
|
60
|
-
arc_summary: z.string().min(1).optional(),
|
|
61
|
-
first_appearance: z.string().min(1).optional(),
|
|
62
|
-
traits: z.array(z.string().min(1)).optional(),
|
|
63
|
-
tags: z.array(z.string().min(1)).optional(),
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
const placeSchema = z.object({
|
|
67
|
-
place_id: z.string().min(1),
|
|
68
|
-
canonical: z.boolean().optional(),
|
|
69
|
-
name: z.string().min(1).optional(),
|
|
70
|
-
associated_characters: z.array(z.string().min(1)).optional(),
|
|
71
|
-
tags: z.array(z.string().min(1)).optional(),
|
|
72
|
-
});
|
|
73
|
-
|
|
74
|
-
const sceneAllowedKeys = new Set(Object.keys(sceneSchema.shape));
|
|
75
|
-
const characterAllowedKeys = new Set(Object.keys(characterSchema.shape));
|
|
76
|
-
const placeAllowedKeys = new Set(Object.keys(placeSchema.shape));
|
|
77
|
-
const sceneLegacyKeys = new Set(["synopsis", "save_the_cat", "change"]);
|
|
78
|
-
|
|
79
|
-
function uniqueItems(items = []) {
|
|
80
|
-
return new Set(items).size === items.length;
|
|
81
|
-
}
|
|
82
|
-
|
|
83
|
-
export function detectMetadataKind(meta) {
|
|
84
|
-
if (meta && typeof meta === "object") {
|
|
85
|
-
if (typeof meta.character_id === "string") return "character";
|
|
86
|
-
if (typeof meta.place_id === "string") return "place";
|
|
87
|
-
return "scene";
|
|
88
|
-
}
|
|
89
|
-
return "scene";
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
function allowedKeysFor(kind) {
|
|
93
|
-
if (kind === "character") return characterAllowedKeys;
|
|
94
|
-
if (kind === "place") return placeAllowedKeys;
|
|
95
|
-
return sceneAllowedKeys;
|
|
96
|
-
}
|
|
97
|
-
|
|
98
|
-
function schemaFor(kind) {
|
|
99
|
-
if (kind === "character") return characterSchema;
|
|
100
|
-
if (kind === "place") return placeSchema;
|
|
101
|
-
return sceneSchema;
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
function validateUniqueArrays(meta, kind, issues) {
|
|
105
|
-
const fields = kind === "scene"
|
|
106
|
-
? ["characters", "places", "tags", "scene_functions", "versions"]
|
|
107
|
-
: kind === "character"
|
|
108
|
-
? ["traits", "tags"]
|
|
109
|
-
: ["associated_characters", "tags"];
|
|
110
|
-
|
|
111
|
-
for (const key of fields) {
|
|
112
|
-
if (Array.isArray(meta[key]) && !uniqueItems(meta[key])) {
|
|
113
|
-
issues.push({
|
|
114
|
-
level: "warning",
|
|
115
|
-
code: "DUPLICATE_ARRAY_ITEMS",
|
|
116
|
-
message: `Array '${key}' contains duplicate values.`,
|
|
117
|
-
});
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
}
|
|
121
|
-
|
|
122
|
-
function validateSceneCharacterReferenceStyle(meta, issues) {
|
|
123
|
-
if (!Array.isArray(meta.characters) || meta.characters.length === 0) return;
|
|
124
|
-
|
|
125
|
-
if (!meta.characters.every(value => typeof value === "string")) return;
|
|
126
|
-
|
|
127
|
-
const hasCanonicalIds = meta.characters.some(value => /^char-/.test(String(value).trim()));
|
|
128
|
-
const hasNonCanonicalEntries = meta.characters.some(value => !/^char-/.test(String(value).trim()));
|
|
129
|
-
|
|
130
|
-
if (!hasCanonicalIds || !hasNonCanonicalEntries) return;
|
|
131
|
-
|
|
132
|
-
issues.push({
|
|
133
|
-
level: "warning",
|
|
134
|
-
code: "MIXED_CHARACTER_REFERENCE_STYLE",
|
|
135
|
-
message: "Scene characters contain mixed canonical and non-canonical references. Prefer canonical character_id values only.",
|
|
136
|
-
});
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
export function validateMetadataObject(meta, { sourcePath, kindHint } = {}) {
|
|
140
|
-
const issues = [];
|
|
141
|
-
const kind = metadataKindSchema.parse(kindHint ?? detectMetadataKind(meta));
|
|
142
|
-
const schema = schemaFor(kind);
|
|
143
|
-
const allowed = allowedKeysFor(kind);
|
|
144
|
-
|
|
145
|
-
if (!meta || typeof meta !== "object" || Array.isArray(meta)) {
|
|
146
|
-
return {
|
|
147
|
-
ok: false,
|
|
148
|
-
kind,
|
|
149
|
-
issues: [{
|
|
150
|
-
level: "error",
|
|
151
|
-
code: "INVALID_METADATA_OBJECT",
|
|
152
|
-
message: "Metadata must be a YAML mapping/object.",
|
|
153
|
-
}],
|
|
154
|
-
};
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
const parsed = schema.safeParse(meta);
|
|
158
|
-
if (!parsed.success) {
|
|
159
|
-
for (const issue of parsed.error.issues) {
|
|
160
|
-
issues.push({
|
|
161
|
-
level: "error",
|
|
162
|
-
code: "SCHEMA_VALIDATION_ERROR",
|
|
163
|
-
message: `${issue.path.join(".") || "metadata"}: ${issue.message}`,
|
|
164
|
-
});
|
|
165
|
-
}
|
|
166
|
-
}
|
|
167
|
-
|
|
168
|
-
for (const key of Object.keys(meta)) {
|
|
169
|
-
if (kind === "scene" && sceneLegacyKeys.has(key)) {
|
|
170
|
-
issues.push({
|
|
171
|
-
level: "warning",
|
|
172
|
-
code: "LEGACY_SCENE_KEY",
|
|
173
|
-
message: `Legacy scene key '${key}' found. Prefer canonical sidecar keys.`,
|
|
174
|
-
});
|
|
175
|
-
continue;
|
|
176
|
-
}
|
|
177
|
-
if (!allowed.has(key)) {
|
|
178
|
-
issues.push({
|
|
179
|
-
level: "warning",
|
|
180
|
-
code: "UNKNOWN_KEY",
|
|
181
|
-
message: `Unknown key '${key}' for ${kind} metadata.`,
|
|
182
|
-
});
|
|
183
|
-
}
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
validateUniqueArrays(meta, kind, issues);
|
|
187
|
-
|
|
188
|
-
if (kind === "scene") {
|
|
189
|
-
validateSceneCharacterReferenceStyle(meta, issues);
|
|
190
|
-
}
|
|
191
|
-
|
|
192
|
-
if (kind === "scene" && sourcePath) {
|
|
193
|
-
const sidecar = sourcePath.endsWith(".meta.yaml");
|
|
194
|
-
if (sidecar && !meta.scene_id) {
|
|
195
|
-
issues.push({
|
|
196
|
-
level: "error",
|
|
197
|
-
code: "MISSING_SCENE_ID",
|
|
198
|
-
message: "Scene sidecar is missing required 'scene_id'.",
|
|
199
|
-
});
|
|
200
|
-
}
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
const hasErrors = issues.some(i => i.level === "error");
|
|
204
|
-
return { ok: !hasErrors, kind, issues };
|
|
205
|
-
}
|
|
206
|
-
|
|
207
|
-
function loadYamlFile(filePath) {
|
|
208
|
-
try {
|
|
209
|
-
const raw = fs.readFileSync(filePath, "utf8");
|
|
210
|
-
const parsed = parseYaml(raw);
|
|
211
|
-
return { ok: true, value: parsed ?? {} };
|
|
212
|
-
} catch (err) {
|
|
213
|
-
return {
|
|
214
|
-
ok: false,
|
|
215
|
-
error: {
|
|
216
|
-
level: "error",
|
|
217
|
-
code: "YAML_PARSE_ERROR",
|
|
218
|
-
message: `Failed to parse YAML: ${err.message}`,
|
|
219
|
-
},
|
|
220
|
-
};
|
|
221
|
-
}
|
|
222
|
-
}
|
|
223
|
-
|
|
224
|
-
function lintSidecar(filePath) {
|
|
225
|
-
const loaded = loadYamlFile(filePath);
|
|
226
|
-
if (!loaded.ok) {
|
|
227
|
-
return {
|
|
228
|
-
file: filePath,
|
|
229
|
-
kind: "scene",
|
|
230
|
-
issues: [loaded.error],
|
|
231
|
-
};
|
|
232
|
-
}
|
|
233
|
-
const result = validateMetadataObject(loaded.value, { sourcePath: filePath });
|
|
234
|
-
return { file: filePath, kind: result.kind, issues: result.issues };
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
function lintFrontmatter(filePath) {
|
|
238
|
-
try {
|
|
239
|
-
const { data } = parseFile(filePath);
|
|
240
|
-
if (!data || !Object.keys(data).length) return null;
|
|
241
|
-
const result = validateMetadataObject(data, { sourcePath: filePath });
|
|
242
|
-
return { file: filePath, kind: result.kind, issues: result.issues };
|
|
243
|
-
} catch (err) {
|
|
244
|
-
return {
|
|
245
|
-
file: filePath,
|
|
246
|
-
kind: "scene",
|
|
247
|
-
issues: [{
|
|
248
|
-
level: "error",
|
|
249
|
-
code: "FRONTMATTER_PARSE_ERROR",
|
|
250
|
-
message: `Failed to parse frontmatter: ${err.message}`,
|
|
251
|
-
}],
|
|
252
|
-
};
|
|
253
|
-
}
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
function loadMetadataForFile(filePath) {
|
|
257
|
-
const sidecar = sidecarPath(filePath);
|
|
258
|
-
if (fs.existsSync(sidecar)) {
|
|
259
|
-
const loaded = loadYamlFile(sidecar);
|
|
260
|
-
return loaded.ok ? loaded.value : null;
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
try {
|
|
264
|
-
const { data } = parseFile(filePath);
|
|
265
|
-
return data && Object.keys(data).length ? data : {};
|
|
266
|
-
} catch {
|
|
267
|
-
return null;
|
|
268
|
-
}
|
|
269
|
-
}
|
|
270
|
-
|
|
271
|
-
function reportPathForFile(filePath) {
|
|
272
|
-
const sidecar = sidecarPath(filePath);
|
|
273
|
-
return fs.existsSync(sidecar) ? sidecar : filePath;
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
function addIssueToReport(reports, filePath, kind, issue) {
|
|
277
|
-
const reportFile = reportPathForFile(filePath);
|
|
278
|
-
const report = reports.find(r => r.file === reportFile);
|
|
279
|
-
if (report) {
|
|
280
|
-
report.issues.push(issue);
|
|
281
|
-
return;
|
|
282
|
-
}
|
|
283
|
-
reports.push({ file: reportFile, kind, issues: [issue] });
|
|
284
|
-
}
|
|
285
|
-
|
|
286
|
-
function shouldWarnNoMetadata(syncDir, filePath) {
|
|
287
|
-
if (!isWorldFile(syncDir, filePath)) return true;
|
|
288
|
-
|
|
289
|
-
const kind = worldEntityKindForPath(syncDir, filePath);
|
|
290
|
-
if (!kind) return false;
|
|
291
|
-
|
|
292
|
-
return isCanonicalWorldEntityFile(syncDir, filePath, {});
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
function compareSidecarAndFrontmatter(filePath, reports) {
|
|
296
|
-
const sidecar = sidecarPath(filePath);
|
|
297
|
-
if (!fs.existsSync(sidecar)) return;
|
|
298
|
-
const sc = reports.find(r => r.file === sidecar);
|
|
299
|
-
if (!sc) return;
|
|
300
|
-
|
|
301
|
-
try {
|
|
302
|
-
const { data } = parseFile(filePath);
|
|
303
|
-
if (!data || !Object.keys(data).length) return;
|
|
304
|
-
const sidecarData = parseYaml(fs.readFileSync(sidecar, "utf8")) ?? {};
|
|
305
|
-
|
|
306
|
-
if (typeof data.scene_id === "string" && typeof sidecarData.scene_id === "string" && data.scene_id !== sidecarData.scene_id) {
|
|
307
|
-
sc.issues.push({
|
|
308
|
-
level: "warning",
|
|
309
|
-
code: "SCENE_ID_MISMATCH",
|
|
310
|
-
message: `scene_id mismatch between frontmatter ('${data.scene_id}') and sidecar ('${sidecarData.scene_id}').`,
|
|
311
|
-
});
|
|
312
|
-
}
|
|
313
|
-
} catch {
|
|
314
|
-
// Parsing failures are already surfaced by individual report entries.
|
|
315
|
-
}
|
|
316
|
-
}
|
|
317
|
-
|
|
318
|
-
export function lintMetadataInSyncDir(syncDir) {
|
|
319
|
-
const reports = [];
|
|
320
|
-
const files = walkFiles(syncDir);
|
|
321
|
-
|
|
322
|
-
for (const sidecar of walkSidecars(syncDir)) {
|
|
323
|
-
reports.push(lintSidecar(sidecar));
|
|
324
|
-
}
|
|
325
|
-
|
|
326
|
-
for (const file of files) {
|
|
327
|
-
if (fs.existsSync(sidecarPath(file))) {
|
|
328
|
-
continue;
|
|
329
|
-
}
|
|
330
|
-
const frontmatterReport = lintFrontmatter(file);
|
|
331
|
-
if (frontmatterReport) {
|
|
332
|
-
reports.push(frontmatterReport);
|
|
333
|
-
} else if (shouldWarnNoMetadata(syncDir, file)) {
|
|
334
|
-
// No sidecar and no frontmatter — file will be silently skipped during sync
|
|
335
|
-
reports.push({
|
|
336
|
-
file,
|
|
337
|
-
kind: "scene",
|
|
338
|
-
issues: [{
|
|
339
|
-
level: "warning",
|
|
340
|
-
code: "NO_METADATA",
|
|
341
|
-
message: "File has no sidecar and no frontmatter — will be skipped during sync (no scene_id).",
|
|
342
|
-
}],
|
|
343
|
-
});
|
|
344
|
-
}
|
|
345
|
-
}
|
|
346
|
-
|
|
347
|
-
for (const file of files) {
|
|
348
|
-
compareSidecarAndFrontmatter(file, reports);
|
|
349
|
-
}
|
|
350
|
-
|
|
351
|
-
// --- Duplicate scene_id detection (cross-file, errors) ---
|
|
352
|
-
const sceneIdToFiles = new Map(); // scene_id → [filePath, ...]
|
|
353
|
-
|
|
354
|
-
for (const sidecar of walkSidecars(syncDir)) {
|
|
355
|
-
try {
|
|
356
|
-
const raw = fs.readFileSync(sidecar, "utf8");
|
|
357
|
-
const meta = parseYaml(raw) ?? {};
|
|
358
|
-
if (typeof meta.scene_id === "string" && meta.scene_id) {
|
|
359
|
-
const arr = sceneIdToFiles.get(meta.scene_id) ?? [];
|
|
360
|
-
arr.push(sidecar);
|
|
361
|
-
sceneIdToFiles.set(meta.scene_id, arr);
|
|
362
|
-
}
|
|
363
|
-
} catch { /* empty */ }
|
|
364
|
-
}
|
|
365
|
-
for (const file of files) {
|
|
366
|
-
if (fs.existsSync(sidecarPath(file))) continue; // already counted via sidecar
|
|
367
|
-
try {
|
|
368
|
-
const { data } = parseFile(file);
|
|
369
|
-
if (typeof data.scene_id === "string" && data.scene_id) {
|
|
370
|
-
const arr = sceneIdToFiles.get(data.scene_id) ?? [];
|
|
371
|
-
arr.push(file);
|
|
372
|
-
sceneIdToFiles.set(data.scene_id, arr);
|
|
373
|
-
}
|
|
374
|
-
} catch { /* empty */ }
|
|
375
|
-
}
|
|
376
|
-
|
|
377
|
-
for (const [sceneId, dupeFiles] of sceneIdToFiles) {
|
|
378
|
-
if (dupeFiles.length < 2) continue;
|
|
379
|
-
const relPaths = dupeFiles.map(f => path.relative(syncDir, f)).join(", ");
|
|
380
|
-
for (const f of dupeFiles) {
|
|
381
|
-
const report = reports.find(r => r.file === f);
|
|
382
|
-
const issue = {
|
|
383
|
-
level: "error",
|
|
384
|
-
code: "DUPLICATE_SCENE_ID",
|
|
385
|
-
message: `scene_id "${sceneId}" is used by ${dupeFiles.length} files: ${relPaths}`,
|
|
386
|
-
};
|
|
387
|
-
if (report) {
|
|
388
|
-
report.issues.push(issue);
|
|
389
|
-
} else {
|
|
390
|
-
reports.push({ file: f, kind: "scene", issues: [issue] });
|
|
391
|
-
}
|
|
392
|
-
}
|
|
393
|
-
}
|
|
394
|
-
|
|
395
|
-
const entityIdToFiles = new Map();
|
|
396
|
-
const canonicalFilesByFolder = new Map();
|
|
397
|
-
|
|
398
|
-
for (const file of files) {
|
|
399
|
-
const kind = worldEntityKindForPath(syncDir, file);
|
|
400
|
-
if (!kind) continue;
|
|
401
|
-
|
|
402
|
-
const meta = loadMetadataForFile(file);
|
|
403
|
-
if (!meta) continue;
|
|
404
|
-
if (!isCanonicalWorldEntityFile(syncDir, file, meta)) continue;
|
|
405
|
-
|
|
406
|
-
const folderKey = worldEntityFolderKey(syncDir, file, kind);
|
|
407
|
-
if (folderKey) {
|
|
408
|
-
const current = canonicalFilesByFolder.get(folderKey) ?? [];
|
|
409
|
-
current.push(file);
|
|
410
|
-
canonicalFilesByFolder.set(folderKey, current);
|
|
411
|
-
}
|
|
412
|
-
|
|
413
|
-
const entityId = kind === "character" ? meta.character_id : meta.place_id;
|
|
414
|
-
if (typeof entityId === "string" && entityId) {
|
|
415
|
-
const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
|
|
416
|
-
const scopeKey = `${kind}:${universe_id ?? "-"}:${project_id ?? "-"}:${entityId}`;
|
|
417
|
-
const current = entityIdToFiles.get(scopeKey) ?? [];
|
|
418
|
-
current.push(file);
|
|
419
|
-
entityIdToFiles.set(scopeKey, current);
|
|
420
|
-
} else {
|
|
421
|
-
addIssueToReport(reports, file, kind, {
|
|
422
|
-
level: "warning",
|
|
423
|
-
code: kind === "character" ? "MISSING_CHARACTER_ID" : "MISSING_PLACE_ID",
|
|
424
|
-
message: `Canonical ${kind} file is missing required '${kind}_id'.`,
|
|
425
|
-
});
|
|
426
|
-
}
|
|
427
|
-
}
|
|
428
|
-
|
|
429
|
-
for (const [folderKey, canonicalFiles] of canonicalFilesByFolder) {
|
|
430
|
-
if (canonicalFiles.length < 2) continue;
|
|
431
|
-
const relPaths = canonicalFiles.map(f => path.relative(syncDir, f)).join(", ");
|
|
432
|
-
for (const file of canonicalFiles) {
|
|
433
|
-
addIssueToReport(reports, file, worldEntityKindForPath(syncDir, file), {
|
|
434
|
-
level: "error",
|
|
435
|
-
code: "MULTIPLE_CANONICAL_FILES",
|
|
436
|
-
message: `Multiple canonical files found in entity folder '${folderKey}': ${relPaths}`,
|
|
437
|
-
});
|
|
438
|
-
}
|
|
439
|
-
}
|
|
440
|
-
|
|
441
|
-
for (const [scopeKey, dupeFiles] of entityIdToFiles) {
|
|
442
|
-
if (dupeFiles.length < 2) continue;
|
|
443
|
-
const entityId = scopeKey.split(":").at(-1);
|
|
444
|
-
const kind = scopeKey.split(":")[0];
|
|
445
|
-
const relPaths = dupeFiles.map(f => path.relative(syncDir, f)).join(", ");
|
|
446
|
-
for (const file of dupeFiles) {
|
|
447
|
-
addIssueToReport(reports, file, kind, {
|
|
448
|
-
level: "error",
|
|
449
|
-
code: kind === "character" ? "DUPLICATE_CHARACTER_ID" : "DUPLICATE_PLACE_ID",
|
|
450
|
-
message: `${kind}_id '${entityId}' is used by ${dupeFiles.length} canonical files: ${relPaths}`,
|
|
451
|
-
});
|
|
452
|
-
}
|
|
453
|
-
}
|
|
454
|
-
|
|
455
|
-
const errors = reports.flatMap(r => r.issues.map(i => ({ ...i, file: r.file, kind: r.kind }))).filter(i => i.level === "error");
|
|
456
|
-
const warnings = reports.flatMap(r => r.issues.map(i => ({ ...i, file: r.file, kind: r.kind }))).filter(i => i.level === "warning");
|
|
457
|
-
|
|
458
|
-
return {
|
|
459
|
-
ok: errors.length === 0,
|
|
460
|
-
syncDir: path.resolve(syncDir),
|
|
461
|
-
files_checked: reports.length,
|
|
462
|
-
error_count: errors.length,
|
|
463
|
-
warning_count: warnings.length,
|
|
464
|
-
errors,
|
|
465
|
-
warnings,
|
|
466
|
-
reports,
|
|
467
|
-
};
|
|
468
|
-
}
|
|
1
|
+
export * from "./src/sync/metadata-lint.js";
|
package/package.json
CHANGED
|
@@ -1,10 +1,39 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hanna84/mcp-writing",
|
|
3
|
-
"version": "2.12.
|
|
3
|
+
"version": "2.12.6",
|
|
4
4
|
"description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
|
|
5
5
|
"homepage": "https://hannasdev.github.io/mcp-writing/",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "index.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./index.js",
|
|
10
|
+
"./index.js": "./index.js",
|
|
11
|
+
"./async-jobs.js": "./async-jobs.js",
|
|
12
|
+
"./async-progress.js": "./async-progress.js",
|
|
13
|
+
"./helpers.js": "./helpers.js",
|
|
14
|
+
"./scene-character-batch.js": "./scene-character-batch.js",
|
|
15
|
+
"./scrivener-direct.js": "./scrivener-direct.js",
|
|
16
|
+
"./importer.js": "./importer.js",
|
|
17
|
+
"./db.js": "./db.js",
|
|
18
|
+
"./sync.js": "./sync.js",
|
|
19
|
+
"./git.js": "./git.js",
|
|
20
|
+
"./world-entity-templates.js": "./world-entity-templates.js",
|
|
21
|
+
"./workflow-catalogue.js": "./workflow-catalogue.js",
|
|
22
|
+
"./runtime-diagnostics.js": "./runtime-diagnostics.js",
|
|
23
|
+
"./metadata-lint.js": "./metadata-lint.js",
|
|
24
|
+
"./scene-character-normalization.js": "./scene-character-normalization.js",
|
|
25
|
+
"./review-bundles.js": "./review-bundles.js",
|
|
26
|
+
"./review-bundles-planner.js": "./review-bundles-planner.js",
|
|
27
|
+
"./review-bundles-renderer.js": "./review-bundles-renderer.js",
|
|
28
|
+
"./review-bundles-writer.js": "./review-bundles-writer.js",
|
|
29
|
+
"./prose-styleguide.js": "./prose-styleguide.js",
|
|
30
|
+
"./prose-styleguide-drift.js": "./prose-styleguide-drift.js",
|
|
31
|
+
"./prose-styleguide-skill.js": "./prose-styleguide-skill.js",
|
|
32
|
+
"./tools/*": "./tools/*",
|
|
33
|
+
"./scripts/*": "./scripts/*",
|
|
34
|
+
"./src/*": "./src/*",
|
|
35
|
+
"./package.json": "./package.json"
|
|
36
|
+
},
|
|
8
37
|
"bin": {
|
|
9
38
|
"mcp-writing": "./bin/mcp-writing.js"
|
|
10
39
|
},
|
|
@@ -12,6 +41,7 @@
|
|
|
12
41
|
"files": [
|
|
13
42
|
"bin/",
|
|
14
43
|
"index.js",
|
|
44
|
+
"src/",
|
|
15
45
|
"async-jobs.js",
|
|
16
46
|
"async-progress.js",
|
|
17
47
|
"helpers.js",
|
|
@@ -52,7 +82,7 @@
|
|
|
52
82
|
"normalize:scene-characters": "node --experimental-sqlite scripts/normalize-scene-characters.mjs",
|
|
53
83
|
"setup:openclaw-env": "sh scripts/setup-openclaw-env.sh",
|
|
54
84
|
"release": "release-it",
|
|
55
|
-
"lint": "eslint *.js scripts/ tools/",
|
|
85
|
+
"lint": "eslint *.js src/ scripts/ tools/",
|
|
56
86
|
"docs": "node scripts/generate-tool-docs.mjs",
|
|
57
87
|
"lint:metadata": "node scripts/lint-metadata.mjs",
|
|
58
88
|
"sync:server-json-version": "node scripts/sync-server-json-version.mjs",
|
package/runtime-diagnostics.js
CHANGED
|
@@ -1,97 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* getRuntimeDiagnostics
|
|
3
|
-
*
|
|
4
|
-
* Inspects the startup environment and returns { warnings, recommendations }.
|
|
5
|
-
* All inputs are passed explicitly so this module has no side effects and
|
|
6
|
-
* is straightforward to test.
|
|
7
|
-
*
|
|
8
|
-
* @param {object} opts
|
|
9
|
-
* @param {string} opts.ownershipGuardModeRaw Raw env value before normalisation
|
|
10
|
-
* @param {string} opts.ownershipGuardMode Normalised value ("warn" | "fail")
|
|
11
|
-
* @param {string} opts.ownershipGuardModeRawDisplay JSON.stringify of the raw value
|
|
12
|
-
* @param {boolean} opts.syncDirWritable
|
|
13
|
-
* @param {string} opts.syncDirAbs Resolved absolute path shown in messages
|
|
14
|
-
* @param {object} opts.syncOwnershipDiagnostics Result of getSyncOwnershipDiagnostics()
|
|
15
|
-
* @param {boolean} opts.gitAvailable
|
|
16
|
-
* @param {boolean} opts.gitEnabled
|
|
17
|
-
* @returns {{ warnings: string[], recommendations: string[] }}
|
|
18
|
-
*/
|
|
19
|
-
export function getRuntimeDiagnostics({
|
|
20
|
-
ownershipGuardModeRaw,
|
|
21
|
-
ownershipGuardMode,
|
|
22
|
-
ownershipGuardModeRawDisplay,
|
|
23
|
-
syncDirWritable,
|
|
24
|
-
syncDirAbs,
|
|
25
|
-
syncOwnershipDiagnostics,
|
|
26
|
-
gitAvailable,
|
|
27
|
-
gitEnabled,
|
|
28
|
-
}) {
|
|
29
|
-
const warnings = [];
|
|
30
|
-
const recommendations = [];
|
|
31
|
-
|
|
32
|
-
if (ownershipGuardModeRaw !== ownershipGuardMode) {
|
|
33
|
-
warnings.push(
|
|
34
|
-
`OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${ownershipGuardModeRawDisplay}. Falling back to 'warn'.`
|
|
35
|
-
);
|
|
36
|
-
recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
if (syncOwnershipDiagnostics.runtime_uid_override_ignored) {
|
|
40
|
-
warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
|
|
41
|
-
recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
if (syncOwnershipDiagnostics.runtime_uid_override_invalid) {
|
|
45
|
-
warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
|
|
46
|
-
recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
if (!syncDirWritable) {
|
|
50
|
-
warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
|
|
51
|
-
recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
|
|
52
|
-
recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.non_runtime_owned_paths > 0) {
|
|
56
|
-
warnings.push(
|
|
57
|
-
`OWNERSHIP_MISMATCH: ${syncOwnershipDiagnostics.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${syncOwnershipDiagnostics.runtime_uid}.`
|
|
58
|
-
);
|
|
59
|
-
recommendations.push(
|
|
60
|
-
`Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${syncDirAbs}"`
|
|
61
|
-
);
|
|
62
|
-
recommendations.push(
|
|
63
|
-
"For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
|
|
64
|
-
);
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
if (ownershipGuardMode === "fail" && syncOwnershipDiagnostics.runtime_uid === 0) {
|
|
68
|
-
warnings.push(
|
|
69
|
-
"OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
|
|
70
|
-
);
|
|
71
|
-
recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.root_owned_paths > 0) {
|
|
75
|
-
warnings.push(
|
|
76
|
-
`ROOT_OWNED_PATHS: ${syncOwnershipDiagnostics.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
|
|
77
|
-
);
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
if (!gitAvailable) {
|
|
81
|
-
warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
|
|
82
|
-
recommendations.push("Install git in the runtime image/environment.");
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
if (gitAvailable && syncDirWritable && !gitEnabled) {
|
|
86
|
-
warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
|
|
87
|
-
recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
if (gitAvailable && !syncDirWritable) {
|
|
91
|
-
recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
|
|
92
|
-
}
|
|
93
|
-
|
|
94
|
-
recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
|
|
95
|
-
|
|
96
|
-
return { warnings, recommendations };
|
|
97
|
-
}
|
|
1
|
+
export * from "./src/runtime/runtime-diagnostics.js";
|