@yawlabs/ansible-mcp 0.1.0 → 0.1.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/dist/index.js CHANGED
@@ -10,203 +10,6 @@ import { createHash } from "crypto";
10
10
  import { existsSync as existsSync2, statSync } from "fs";
11
11
  import { resolve } from "path";
12
12
 
13
- // src/ansibleDoc.ts
14
- var asText = (d) => Array.isArray(d) ? d.map(String).join(" ") : typeof d === "string" ? d : d === void 0 || d === null ? "" : String(d);
15
- function parseDocJson(text2) {
16
- const out = /* @__PURE__ */ new Map();
17
- const t = text2.trim();
18
- if (!t) return out;
19
- let data;
20
- try {
21
- data = JSON.parse(t);
22
- } catch (e) {
23
- throw new Error(`ansible-doc --json did not return JSON (${e instanceof Error ? e.message : String(e)}).`);
24
- }
25
- for (const [key, entry] of Object.entries(data ?? {})) {
26
- const doc = entry?.doc;
27
- if (!doc || typeof doc !== "object") continue;
28
- out.set(key, {
29
- key,
30
- fqcn: String(doc.plugin_name ?? key),
31
- collection: String(doc.collection ?? ""),
32
- filename: String(doc.filename ?? ""),
33
- hasAction: doc.has_action === true,
34
- shortDescription: asText(doc.short_description),
35
- description: asText(doc.description),
36
- options: doc.options ?? {},
37
- deprecated: doc.deprecated && typeof doc.deprecated === "object" ? doc.deprecated : void 0,
38
- checkMode: doc.attributes?.check_mode?.support,
39
- requirements: Array.isArray(doc.requirements) ? doc.requirements.map(String) : [],
40
- returns: entry.return && typeof entry.return === "object" ? entry.return : null,
41
- examples: typeof entry.examples === "string" ? entry.examples : "",
42
- versionAdded: doc.version_added
43
- });
44
- }
45
- return out;
46
- }
47
- var TOMBSTONE = /\[ERROR\]: (?:\w+ )?(\S+) Missing documentation \(or could not parse documentation\): (?:The '[^']+' \w+ has been removed\. )?(.*?) ?This feature was removed from collection '([^']+)' version ([^\s]+?)\.?$/;
48
- function classifyDocStderr(stderr) {
49
- const r = { missing: [], deprecations: [], tombstones: [], errors: [] };
50
- for (const line of stderr.split(/\r?\n/)) {
51
- let m = /^\[WARNING\]: (\S+) was not found$/.exec(line);
52
- if (m) {
53
- if (!r.missing.includes(m[1])) r.missing.push(m[1]);
54
- continue;
55
- }
56
- m = /^\[DEPRECATION WARNING\]: (\S+) has been deprecated\. (.*)$/.exec(line);
57
- if (m) {
58
- r.deprecations.push({ name: m[1], text: m[2] });
59
- continue;
60
- }
61
- m = TOMBSTONE.exec(line);
62
- if (m) {
63
- if (!r.tombstones.some((t) => t.name === m[1])) {
64
- r.tombstones.push({ name: m[1], text: m[2].trim(), collection: m[3], version: m[4] });
65
- }
66
- continue;
67
- }
68
- if (line.startsWith("[ERROR]:")) r.errors.push(line.slice(9).trim());
69
- }
70
- return r;
71
- }
72
- function choicesOf(o) {
73
- if (!o?.choices) return null;
74
- return Array.isArray(o.choices) ? o.choices : Object.keys(o.choices);
75
- }
76
- function subOptionsOf(o) {
77
- return o?.suboptions ?? o?.options ?? null;
78
- }
79
- var typeOf = (o) => o?.type ?? "str";
80
- function findOption(options, name) {
81
- if (Object.hasOwn(options, name)) return [name, options[name], void 0];
82
- for (const [k, o] of Object.entries(options)) {
83
- if (o.aliases?.includes(name)) return [k, o, name];
84
- }
85
- return null;
86
- }
87
- function oneLine(desc, max) {
88
- let d = asText(desc).replace(/\s+/g, " ").trim();
89
- if (max && d.length > max) d = `${d.slice(0, max)}...`;
90
- return d;
91
- }
92
- var fmtDefault = (v) => JSON.stringify(v);
93
- function optionLine(name, o, pad, descLen, majorFloor) {
94
- const t = typeOf(o);
95
- const type = o.elements ? `${t} of ${o.elements}` : t;
96
- const flags = [];
97
- if (o.required) flags.push("[required]");
98
- if (o.default !== void 0 && o.default !== null)
99
- flags.push(o.no_log ? "[default: (no_log)]" : `[default: ${fmtDefault(o.default)}]`);
100
- const ch = choicesOf(o);
101
- if (ch) flags.push(`[choices: ${ch.map((c) => String(c)).join("|")}]`);
102
- if (o.aliases?.length) flags.push(`[aliases: ${o.aliases.join(", ")}]`);
103
- if (o.no_log) flags.push("[no_log]");
104
- if (o.deprecated) {
105
- const d = o.deprecated;
106
- flags.push(
107
- `[deprecated${d.removed_in ? `: removed in ${d.removed_in}` : ""}${d.alternative ? `, ${oneLine(d.alternative, 80)}` : ""}]`
108
- );
109
- }
110
- if (o.version_added && majorFloor && o.version_added_collection && newerThan(o.version_added, majorFloor)) {
111
- flags.push(`[added in ${o.version_added_collection} ${o.version_added}]`);
112
- }
113
- const desc = oneLine(o.description, descLen);
114
- return `${pad}${name} (${type})${flags.length ? ` ${flags.join(" ")}` : ""}${desc ? ` - ${desc}` : ""}`;
115
- }
116
- function newerThan(v, floor) {
117
- const a = String(v).split(".").map(Number);
118
- const b = floor.split(".").map(Number);
119
- for (let i = 0; i < 3; i++) {
120
- if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
121
- }
122
- return false;
123
- }
124
- function renderOptions(options, depth, descLen, majorFloor) {
125
- const lines = [];
126
- const pad = " ".repeat(depth);
127
- for (const name of Object.keys(options).sort()) {
128
- const o = options[name];
129
- lines.push(optionLine(name, o, pad, descLen, majorFloor));
130
- const sub = subOptionsOf(o);
131
- if (sub) lines.push(...renderOptions(sub, depth + 1, descLen, majorFloor));
132
- }
133
- return lines;
134
- }
135
- function renderModuleDoc(r) {
136
- const d = r.doc;
137
- const resolved = r.asked !== d.fqcn ? ` [resolved from '${r.asked}']` : "";
138
- let head = `${d.fqcn} (${r.type}, ${r.source})${resolved}`;
139
- if (d.deprecated) {
140
- const dep = d.deprecated;
141
- head += ` [DEPRECATED${dep.removed_in ? `: removed in ${dep.removed_in}` : ""}${dep.why ? `; ${oneLine(dep.why, 120)}` : ""}${dep.alternative ? `; ${oneLine(dep.alternative, 120)}` : ""}]`;
142
- }
143
- if (d.hasAction) head += " [has action plugin]";
144
- if (d.shortDescription) head += ` - ${d.shortDescription}`;
145
- const lines = [head];
146
- const meta = [];
147
- if (d.checkMode) meta.push(`check_mode: ${d.checkMode}`);
148
- if (d.requirements.length) meta.push(`requirements: ${d.requirements.join("; ")}`);
149
- if (meta.length) lines.push(meta.join(" | "));
150
- const opts = d.options ?? {};
151
- lines.push(`options (${Object.keys(opts).length}):`);
152
- lines.push(...renderOptions(opts, 1, r.descriptionChars, r.majorFloor));
153
- if (r.type === "module") {
154
- lines.push(
155
- "not in ansible-doc output: cross-option rules (mutually_exclusive, required_if, ...); see the module description and notes"
156
- );
157
- }
158
- if (r.includeReturn && r.type === "module") {
159
- const ret = Object.entries(d.returns ?? {});
160
- if (ret.length === 0) {
161
- lines.push("returns: (none documented)");
162
- } else {
163
- lines.push(`returns (${ret.length}):`);
164
- for (const [k, v] of ret.sort(([a], [b]) => a < b ? -1 : 1)) {
165
- const desc = oneLine(v?.description, r.descriptionChars);
166
- lines.push(
167
- ` ${k} (${v?.type ?? "?"}${v?.returned ? `, ${oneLine(v.returned, 40)}` : ""})${desc ? ` - ${desc}` : ""}`
168
- );
169
- }
170
- }
171
- }
172
- if (r.includeExamples && d.examples.trim()) {
173
- lines.push("examples:");
174
- lines.push(...d.examples.replace(/^\n+|\s+$/g, "").split("\n"));
175
- }
176
- return lines.join("\n");
177
- }
178
- function collectionRootOf(filename) {
179
- const m = /^(.*\/ansible_collections\/[^/]+\/[^/]+)\//.exec(filename.replace(/\\/g, "/"));
180
- return m ? m[1] : null;
181
- }
182
- function collectionsPathOf(filename) {
183
- const m = /^(.*)\/ansible_collections\//.exec(filename.replace(/\\/g, "/"));
184
- return m ? m[1] : null;
185
- }
186
- var PLUGIN_TYPES = [
187
- "module",
188
- "lookup",
189
- "filter",
190
- "test",
191
- "callback",
192
- "connection",
193
- "inventory",
194
- "become",
195
- "cache",
196
- "vars",
197
- "strategy",
198
- "shell",
199
- "cliconf",
200
- "httpapi",
201
- "netconf",
202
- "keyword",
203
- "role"
204
- ];
205
- function isPluginType(t) {
206
- return PLUGIN_TYPES.includes(t);
207
- }
208
- var BAD_TYPE_MESSAGE = `type must be one of ${PLUGIN_TYPES.join(", ")}`;
209
-
210
13
  // src/redact.ts
211
14
  var VAULTED = "<vaulted>";
212
15
  var REDACTED_VALUE = "(redacted: contains a secret value)";
@@ -364,7 +167,7 @@ var SHAPES = [
364
167
  /LS0tLS1CRUdJTi[A-Za-z0-9+/=]{0,40}(UFJJVkFURSBLRVk|BSSVZBVEUgS0VZ|UklWQVRFIEtFW)/
365
168
  ];
366
169
  var VAULT_TEXT = /^\s*\$ANSIBLE_VAULT;/;
367
- var URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/]+):([^\s@/]+)@/gi;
170
+ var URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/]*):([^\s@/]+)@/gi;
368
171
  function hasSecretShape(s) {
369
172
  return SHAPES.some((re) => re.test(s));
370
173
  }
@@ -492,11 +295,13 @@ var Redactor = class {
492
295
  const url = maskUrlPasswords(v);
493
296
  if (url !== null) this.counts.url++;
494
297
  const inline = maskInlineCredentials(url ?? v);
495
- if (inline !== null) {
496
- this.counts.shape++;
497
- return inline;
298
+ if (inline !== null) this.counts.shape++;
299
+ const masked = inline ?? url;
300
+ if (masked !== null) {
301
+ if (!this.matches(masked)) return masked;
302
+ this.counts.value++;
303
+ return new Hidden(REDACTED_VALUE);
498
304
  }
499
- if (url !== null) return url;
500
305
  if (this.matches(v)) {
501
306
  this.counts.value++;
502
307
  return new Hidden(REDACTED_VALUE);
@@ -542,11 +347,212 @@ var Redactor = class {
542
347
  return parts.length ? `redacted: ${parts.join(", ")}` : "";
543
348
  }
544
349
  };
350
+ function redactStandalone(value, key) {
351
+ const red = new Redactor();
352
+ red.learn(value, [key]);
353
+ return red.render(value, [key]);
354
+ }
545
355
  function stringify(v) {
546
356
  if (v instanceof Hidden) return v.text;
547
357
  return JSON.stringify(v, (_k, x) => x instanceof Hidden ? x.text : x) ?? "null";
548
358
  }
549
359
 
360
+ // src/ansibleDoc.ts
361
+ var asText = (d) => Array.isArray(d) ? d.map(String).join(" ") : typeof d === "string" ? d : d === void 0 || d === null ? "" : String(d);
362
+ function parseDocJson(text2) {
363
+ const out = /* @__PURE__ */ new Map();
364
+ const t = text2.trim();
365
+ if (!t) return out;
366
+ let data;
367
+ try {
368
+ data = JSON.parse(t);
369
+ } catch (e) {
370
+ throw new Error(`ansible-doc --json did not return JSON (${e instanceof Error ? e.message : String(e)}).`);
371
+ }
372
+ for (const [key, entry] of Object.entries(data ?? {})) {
373
+ const doc = entry?.doc;
374
+ if (!doc || typeof doc !== "object") continue;
375
+ out.set(key, {
376
+ key,
377
+ fqcn: String(doc.plugin_name ?? key),
378
+ collection: String(doc.collection ?? ""),
379
+ filename: String(doc.filename ?? ""),
380
+ hasAction: doc.has_action === true,
381
+ shortDescription: asText(doc.short_description),
382
+ description: asText(doc.description),
383
+ options: doc.options ?? {},
384
+ deprecated: doc.deprecated && typeof doc.deprecated === "object" ? doc.deprecated : void 0,
385
+ checkMode: doc.attributes?.check_mode?.support,
386
+ requirements: Array.isArray(doc.requirements) ? doc.requirements.map(String) : [],
387
+ returns: entry.return && typeof entry.return === "object" ? entry.return : null,
388
+ examples: typeof entry.examples === "string" ? entry.examples : "",
389
+ versionAdded: doc.version_added
390
+ });
391
+ }
392
+ return out;
393
+ }
394
+ var TOMBSTONE = /\[ERROR\]: (?:\w+ )?(\S+) Missing documentation \(or could not parse documentation\): (?:The '[^']+' \w+ has been removed\. )?(.*?) ?This feature was removed from collection '([^']+)' version ([^\s]+?)\.?$/;
395
+ function classifyDocStderr(stderr) {
396
+ const r = { missing: [], deprecations: [], tombstones: [], errors: [] };
397
+ for (const line of stderr.split(/\r?\n/)) {
398
+ let m = /^\[WARNING\]: (\S+) was not found$/.exec(line);
399
+ if (m) {
400
+ if (!r.missing.includes(m[1])) r.missing.push(m[1]);
401
+ continue;
402
+ }
403
+ m = /^\[DEPRECATION WARNING\]: (\S+) has been deprecated\. (.*)$/.exec(line);
404
+ if (m) {
405
+ r.deprecations.push({ name: m[1], text: m[2] });
406
+ continue;
407
+ }
408
+ m = TOMBSTONE.exec(line);
409
+ if (m) {
410
+ if (!r.tombstones.some((t) => t.name === m[1])) {
411
+ r.tombstones.push({ name: m[1], text: m[2].trim(), collection: m[3], version: m[4] });
412
+ }
413
+ continue;
414
+ }
415
+ if (line.startsWith("[ERROR]:")) r.errors.push(line.slice(9).trim());
416
+ }
417
+ return r;
418
+ }
419
+ function choicesOf(o) {
420
+ if (!o?.choices) return null;
421
+ return Array.isArray(o.choices) ? o.choices : Object.keys(o.choices);
422
+ }
423
+ function subOptionsOf(o) {
424
+ return o?.suboptions ?? o?.options ?? null;
425
+ }
426
+ var typeOf = (o) => o?.type ?? "str";
427
+ function findOption(options, name) {
428
+ if (Object.hasOwn(options, name)) return [name, options[name], void 0];
429
+ for (const [k, o] of Object.entries(options)) {
430
+ if (o.aliases?.includes(name)) return [k, o, name];
431
+ }
432
+ return null;
433
+ }
434
+ function oneLine(desc, max) {
435
+ let d = asText(desc).replace(/\s+/g, " ").trim();
436
+ if (max && d.length > max) d = `${d.slice(0, max)}...`;
437
+ return d;
438
+ }
439
+ function optionLine(name, o, pad, descLen, majorFloor) {
440
+ const t = typeOf(o);
441
+ const type = o.elements ? `${t} of ${o.elements}` : t;
442
+ const flags = [];
443
+ if (o.required) flags.push("[required]");
444
+ if (o.default !== void 0 && o.default !== null)
445
+ flags.push(o.no_log ? "[default: (no_log)]" : `[default: ${redactStandalone(o.default, name)}]`);
446
+ const ch = choicesOf(o);
447
+ if (ch) flags.push(`[choices: ${ch.map((c) => String(c)).join("|")}]`);
448
+ if (o.aliases?.length) flags.push(`[aliases: ${o.aliases.join(", ")}]`);
449
+ if (o.no_log) flags.push("[no_log]");
450
+ if (o.deprecated) {
451
+ const d = o.deprecated;
452
+ flags.push(
453
+ `[deprecated${d.removed_in ? `: removed in ${d.removed_in}` : ""}${d.alternative ? `, ${oneLine(d.alternative, 80)}` : ""}]`
454
+ );
455
+ }
456
+ if (o.version_added && majorFloor && o.version_added_collection && newerThan(o.version_added, majorFloor)) {
457
+ flags.push(`[added in ${o.version_added_collection} ${o.version_added}]`);
458
+ }
459
+ const desc = oneLine(o.description, descLen);
460
+ return `${pad}${name} (${type})${flags.length ? ` ${flags.join(" ")}` : ""}${desc ? ` - ${desc}` : ""}`;
461
+ }
462
+ function newerThan(v, floor) {
463
+ const a = String(v).split(".").map(Number);
464
+ const b = floor.split(".").map(Number);
465
+ for (let i = 0; i < 3; i++) {
466
+ if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
467
+ }
468
+ return false;
469
+ }
470
+ function renderOptions(options, depth, descLen, majorFloor) {
471
+ const lines = [];
472
+ const pad = " ".repeat(depth);
473
+ for (const name of Object.keys(options).sort()) {
474
+ const o = options[name];
475
+ lines.push(optionLine(name, o, pad, descLen, majorFloor));
476
+ const sub = subOptionsOf(o);
477
+ if (sub) lines.push(...renderOptions(sub, depth + 1, descLen, majorFloor));
478
+ }
479
+ return lines;
480
+ }
481
+ function renderModuleDoc(r) {
482
+ const d = r.doc;
483
+ const resolved = r.asked !== d.fqcn ? ` [resolved from '${r.asked}']` : "";
484
+ let head = `${d.fqcn} (${r.type}, ${r.source})${resolved}`;
485
+ if (d.deprecated) {
486
+ const dep = d.deprecated;
487
+ head += ` [DEPRECATED${dep.removed_in ? `: removed in ${dep.removed_in}` : ""}${dep.why ? `; ${oneLine(dep.why, 120)}` : ""}${dep.alternative ? `; ${oneLine(dep.alternative, 120)}` : ""}]`;
488
+ }
489
+ if (d.hasAction) head += " [has action plugin]";
490
+ if (d.shortDescription) head += ` - ${d.shortDescription}`;
491
+ const lines = [head];
492
+ const meta = [];
493
+ if (d.checkMode) meta.push(`check_mode: ${d.checkMode}`);
494
+ if (d.requirements.length) meta.push(`requirements: ${d.requirements.join("; ")}`);
495
+ if (meta.length) lines.push(meta.join(" | "));
496
+ const opts = d.options ?? {};
497
+ lines.push(`options (${Object.keys(opts).length}):`);
498
+ lines.push(...renderOptions(opts, 1, r.descriptionChars, r.majorFloor));
499
+ if (r.type === "module") {
500
+ lines.push(
501
+ "not in ansible-doc output: cross-option rules (mutually_exclusive, required_if, ...); see the module description and notes"
502
+ );
503
+ }
504
+ if (r.includeReturn && r.type === "module") {
505
+ const ret = Object.entries(d.returns ?? {});
506
+ if (ret.length === 0) {
507
+ lines.push("returns: (none documented)");
508
+ } else {
509
+ lines.push(`returns (${ret.length}):`);
510
+ for (const [k, v] of ret.sort(([a], [b]) => a < b ? -1 : 1)) {
511
+ const desc = oneLine(v?.description, r.descriptionChars);
512
+ lines.push(
513
+ ` ${k} (${v?.type ?? "?"}${v?.returned ? `, ${oneLine(v.returned, 40)}` : ""})${desc ? ` - ${desc}` : ""}`
514
+ );
515
+ }
516
+ }
517
+ }
518
+ if (r.includeExamples && d.examples.trim()) {
519
+ lines.push("examples:");
520
+ lines.push(...d.examples.replace(/^\n+|\s+$/g, "").split("\n"));
521
+ }
522
+ return lines.join("\n");
523
+ }
524
+ function collectionRootOf(filename) {
525
+ const m = /^(.*\/ansible_collections\/[^/]+\/[^/]+)\//.exec(filename.replace(/\\/g, "/"));
526
+ return m ? m[1] : null;
527
+ }
528
+ function collectionsPathOf(filename) {
529
+ const m = /^(.*)\/ansible_collections\//.exec(filename.replace(/\\/g, "/"));
530
+ return m ? m[1] : null;
531
+ }
532
+ var PLUGIN_TYPES = [
533
+ "module",
534
+ "lookup",
535
+ "filter",
536
+ "test",
537
+ "callback",
538
+ "connection",
539
+ "inventory",
540
+ "become",
541
+ "cache",
542
+ "vars",
543
+ "strategy",
544
+ "shell",
545
+ "cliconf",
546
+ "httpapi",
547
+ "netconf",
548
+ "keyword",
549
+ "role"
550
+ ];
551
+ function isPluginType(t) {
552
+ return PLUGIN_TYPES.includes(t);
553
+ }
554
+ var BAD_TYPE_MESSAGE = `type must be one of ${PLUGIN_TYPES.join(", ")}`;
555
+
550
556
  // src/config.ts
551
557
  function parseConfigDump(text2) {
552
558
  let data;
@@ -961,24 +967,44 @@ var AnsibleRunner = class {
961
967
  const d = this.distro();
962
968
  return d ? `\\\\wsl.localhost\\${d}${p.replace(/\//g, "\\")}` : null;
963
969
  }
964
- /** The Ansible side's environment (prefix mode; learned once per process). */
970
+ /**
971
+ * The Ansible side's environment (prefix mode; learned once per process). A
972
+ * spawn failure, a non-zero exit or an empty listing rejects and is not
973
+ * cached, so the next call asks again.
974
+ */
965
975
  sideEnv() {
966
976
  if (!this.prefixed) return Promise.resolve(process.env);
967
- this.sideEnvCache ??= this.raw("env", [], {}).then((r) => {
968
- const out = {};
969
- for (const line of r.stdout.split("\n")) {
970
- const i = line.indexOf("=");
971
- if (i > 0) out[line.slice(0, i)] = line.slice(i + 1);
972
- }
973
- return out;
974
- });
977
+ if (!this.sideEnvCache) {
978
+ const p = this.raw("env", [], {}).then((r) => {
979
+ const out = {};
980
+ for (const line of r.stdout.split("\n")) {
981
+ const i = line.indexOf("=");
982
+ if (i > 0) out[line.slice(0, i)] = line.slice(i + 1);
983
+ }
984
+ if (r.code !== 0 || Object.keys(out).length === 0) {
985
+ throw new Error(
986
+ `could not read the Ansible side's environment (env exit ${r.code})${r.stderr.trim() ? `: ${r.stderr.trim().slice(0, 512)}` : ""}`
987
+ );
988
+ }
989
+ return out;
990
+ });
991
+ p.catch(() => {
992
+ this.sideEnvCache = null;
993
+ });
994
+ this.sideEnvCache = p;
995
+ }
975
996
  return this.sideEnvCache;
976
997
  }
977
998
  /** Ansible-side cache root: ANSIBLE_MCP_REMOTE_CACHE, else $HOME/.cache/ansible-mcp (never /tmp, F24). */
978
999
  async sideCacheRoot() {
979
1000
  if (!this.prefixed) return this.localCache;
980
1001
  if (this.remoteCacheOverride) return this.remoteCacheOverride;
981
- const home = (await this.sideEnv()).HOME || "/tmp";
1002
+ const home = (await this.sideEnv()).HOME;
1003
+ if (!home) {
1004
+ throw new Error(
1005
+ "HOME is not set on the Ansible side, so there is no cache dir (never /tmp, F24). Set ANSIBLE_MCP_REMOTE_CACHE to an Ansible-side directory."
1006
+ );
1007
+ }
982
1008
  return posix.join(home, ".cache", "ansible-mcp");
983
1009
  }
984
1010
  /**
@@ -1126,10 +1152,17 @@ var AnsibleRunner = class {
1126
1152
  const r = await this.raw("mv", ["-T", "--", from, to], {});
1127
1153
  return r.code === 0;
1128
1154
  }
1129
- /** Recursive delete of a `.tmp-*` dir, only under `guardRoot` (asserted). */
1155
+ /**
1156
+ * Recursive delete of a `.tmp-*` dir, only under `guardRoot` (asserted): the
1157
+ * last segment must start with `.tmp-`, and no segment of either path may be
1158
+ * `.` or `..` (a plain prefix test would accept `<root>/../x/.tmp-y`).
1159
+ */
1130
1160
  async sideRemoveTemp(p, guardRoot) {
1131
- const norm = (s) => s.replace(/\\/g, "/").replace(/\/+$/, "");
1132
- if (!norm(p).startsWith(`${norm(guardRoot)}/`) || !norm(p).includes("/.tmp-")) {
1161
+ const segs = (s) => s.replace(/\\/g, "/").replace(/\/+$/, "").split("/");
1162
+ const ps = segs(p);
1163
+ const rs = segs(guardRoot);
1164
+ const dotted = (x) => x.some((s) => s === "." || s === "..");
1165
+ if (dotted(ps) || dotted(rs) || ps.length <= rs.length || rs.some((s, i) => s !== ps[i]) || !ps.at(-1).startsWith(".tmp-")) {
1133
1166
  throw new Error(`refusing to remove ${p}: not a temp dir under ${guardRoot}`);
1134
1167
  }
1135
1168
  if (!this.prefixed) {
@@ -1174,6 +1207,7 @@ var AnsibleContext = class {
1174
1207
  configCache = /* @__PURE__ */ new Map();
1175
1208
  versionCache = null;
1176
1209
  fingerprints = /* @__PURE__ */ new Map();
1210
+ /** Per-name doc results; `deprecations` replays the batch's warnings naming that entry on a hit. */
1177
1211
  docCache = /* @__PURE__ */ new Map();
1178
1212
  listCache = /* @__PURE__ */ new Map();
1179
1213
  /** Serializes ansible_upgrade_impact calls in this process. */
@@ -1331,6 +1365,9 @@ ${r.stderr.trim().slice(0, 2048)}`);
1331
1365
  * tombstone retry (F2: one tombstone fails the whole batch, so it is recorded
1332
1366
  * and the batch re-run without it). `collectionsPath` overrides
1333
1367
  * ANSIBLE_COLLECTIONS_PATH (upgrade targets); those results are not cached.
1368
+ * A name starting with `-` is never a plugin name: it is reported missing and
1369
+ * never reaches argv (task keys are user data; `-M x` would be an option), and
1370
+ * the names follow `--` besides.
1334
1371
  */
1335
1372
  async docs(p, names, opts = {}) {
1336
1373
  const type = opts.type ?? "module";
@@ -1340,20 +1377,31 @@ ${r.stderr.trim().slice(0, 2048)}`);
1340
1377
  const fp = cacheable ? await this.fingerprint(p) : "";
1341
1378
  const todo = [];
1342
1379
  for (const n of unique) {
1380
+ if (n.startsWith("-")) {
1381
+ result.missing.push(n);
1382
+ continue;
1383
+ }
1343
1384
  const c = cacheable ? this.docCache.get(`${fp}|${type}|${n}`) : void 0;
1344
1385
  if (!c) todo.push(n);
1345
- else if ("kind" in c && c.kind === "doc") result.docs.set(n, c.doc);
1346
- else if ("kind" in c && c.kind === "missing") result.missing.push(n);
1347
- else result.tombstones.push(c);
1386
+ else if ("kind" in c) {
1387
+ if (c.kind === "doc" && c.doc) result.docs.set(n, c.doc);
1388
+ else result.missing.push(n);
1389
+ result.deprecations.push(...c.deprecations);
1390
+ } else result.tombstones.push(c);
1348
1391
  }
1349
1392
  const env = {};
1350
1393
  if (opts.collectionsPath) env.ANSIBLE_COLLECTIONS_PATH = opts.collectionsPath;
1351
1394
  for (let i = 0; i < todo.length; i += DOC_BATCH) {
1352
1395
  let batch = todo.slice(i, i + DOC_BATCH);
1353
1396
  for (let attempt = 0; batch.length > 0 && attempt <= batch.length; attempt++) {
1354
- const r = await this.runSafe(p, "ansible-doc", ["--json", "-t", type, ...opts.extraArgs ?? [], ...batch], {
1355
- env
1356
- });
1397
+ const r = await this.runSafe(
1398
+ p,
1399
+ "ansible-doc",
1400
+ ["--json", "-t", type, ...opts.extraArgs ?? [], "--", ...batch],
1401
+ {
1402
+ env
1403
+ }
1404
+ );
1357
1405
  const st = classifyDocStderr(r.stderr);
1358
1406
  if (r.code !== 0) {
1359
1407
  const tomb = st.tombstones.filter((t) => batch.includes(t.name));
@@ -1371,12 +1419,14 @@ ${r.stderr.trim().slice(0, 2048)}`);
1371
1419
  const docs = parseDocJson(r.stdout);
1372
1420
  for (const n of batch) {
1373
1421
  const d = docs.get(n);
1374
- if (d) {
1375
- result.docs.set(n, d);
1376
- if (cacheable) this.docCache.set(`${fp}|${type}|${n}`, { kind: "doc", doc: d });
1377
- } else {
1378
- result.missing.push(n);
1379
- if (cacheable) this.docCache.set(`${fp}|${type}|${n}`, { kind: "missing" });
1422
+ if (d) result.docs.set(n, d);
1423
+ else result.missing.push(n);
1424
+ if (cacheable) {
1425
+ const deprecations = st.deprecations.filter((x) => x.name === n);
1426
+ this.docCache.set(
1427
+ `${fp}|${type}|${n}`,
1428
+ d ? { kind: "doc", doc: d, deprecations } : { kind: "missing", deprecations }
1429
+ );
1380
1430
  }
1381
1431
  }
1382
1432
  result.deprecations.push(...st.deprecations);
@@ -1422,11 +1472,11 @@ import { z } from "zod";
1422
1472
 
1423
1473
  // src/handlers.ts
1424
1474
  import { readdirSync as readdirSync5, readFileSync as readFileSync4 } from "fs";
1425
- import { dirname as dirname3, join as join6 } from "path";
1475
+ import { dirname as dirname3, join as join6, normalize } from "path";
1426
1476
 
1427
1477
  // src/project.ts
1428
- import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, statSync as statSync2 } from "fs";
1429
- import { dirname, join as join2, posix as posix2 } from "path";
1478
+ import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync2, realpathSync, statSync as statSync2 } from "fs";
1479
+ import { dirname, isAbsolute, join as join2, posix as posix2 } from "path";
1430
1480
 
1431
1481
  // src/yaml.ts
1432
1482
  import {
@@ -1464,6 +1514,8 @@ var pyFalse = {
1464
1514
  resolve: () => false
1465
1515
  };
1466
1516
  var NULL_SCALAR = (line) => ({ kind: "scalar", value: null, line, raw: "" });
1517
+ var MAX_ALIAS_EXPANSION = 1e5;
1518
+ var ALIAS_LIMIT_ERROR = "alias expansion limit exceeded";
1467
1519
  function parseYaml(src) {
1468
1520
  const lc = new LineCounter();
1469
1521
  const docs = parseAllDocuments(src, {
@@ -1487,6 +1539,16 @@ function parseYaml(src) {
1487
1539
  const line = (offset) => offset === void 0 ? 0 : lc.linePos(offset).line;
1488
1540
  const convertedCache = /* @__PURE__ */ new WeakMap();
1489
1541
  const inProgress = /* @__PURE__ */ new WeakSet();
1542
+ const sizes = /* @__PURE__ */ new WeakMap();
1543
+ let aliasBudget = MAX_ALIAS_EXPANSION;
1544
+ let aliasLimitHit = false;
1545
+ const sizeOf = (y) => {
1546
+ const known = sizes.get(y);
1547
+ if (known !== void 0) return known;
1548
+ const n = y.kind === "scalar" ? 1 : y.kind === "seq" ? y.items.reduce((a, i) => a + sizeOf(i), 1) : y.entries.reduce((a, e) => a + sizeOf(e.value), 1);
1549
+ sizes.set(y, n);
1550
+ return n;
1551
+ };
1490
1552
  const mergeEntries = (node) => {
1491
1553
  const anchors = isAlias(node) ? [node] : isSeq(node) ? node.items : [];
1492
1554
  const out = [];
@@ -1498,10 +1560,23 @@ function parseYaml(src) {
1498
1560
  }
1499
1561
  return out;
1500
1562
  };
1563
+ const aliasKey = (k, fallbackLine) => {
1564
+ const conv = convert(k, fallbackLine);
1565
+ return conv.kind === "scalar" && conv.value !== null && typeof conv.value !== "object" ? String(conv.value) : String(k);
1566
+ };
1501
1567
  const convert = (node, fallbackLine) => {
1502
1568
  if (node === null || node === void 0) return NULL_SCALAR(fallbackLine);
1503
1569
  if (isAlias(node)) {
1504
- return NULL_SCALAR(line(node.range?.[0]));
1570
+ const target = node.resolve(docs[0]);
1571
+ const aliasLine = line(node.range?.[0]);
1572
+ if (!target || aliasLimitHit) return NULL_SCALAR(aliasLine);
1573
+ const out = convert(target, aliasLine);
1574
+ aliasBudget -= sizeOf(out);
1575
+ if (aliasBudget < 0) {
1576
+ aliasLimitHit = true;
1577
+ return NULL_SCALAR(aliasLine);
1578
+ }
1579
+ return out;
1505
1580
  }
1506
1581
  const n = node;
1507
1582
  const cached = convertedCache.get(n);
@@ -1535,7 +1610,7 @@ function parseYaml(src) {
1535
1610
  for (const e of mergeEntries(item.value)) merged.push(e);
1536
1611
  continue;
1537
1612
  }
1538
- const keyText = isScalar(k) ? String(k.value) : k ? String(k) : "";
1613
+ const keyText = isScalar(k) ? String(k.value) : isAlias(k) ? aliasKey(k, start) : k ? String(k) : "";
1539
1614
  const keyLine = line(k?.range?.[0]) || start;
1540
1615
  if (seen.has(keyText)) duplicates.push({ key: keyText, line: keyLine });
1541
1616
  seen.add(keyText);
@@ -1574,6 +1649,7 @@ function parseYaml(src) {
1574
1649
  for (const e of d.errors) errors.push(e.message.split("\n")[0]);
1575
1650
  if (i === 0) root = d.contents ? convert(d.contents, 1) : null;
1576
1651
  }
1652
+ if (aliasLimitHit) errors.push(`${ALIAS_LIMIT_ERROR} (more than ${MAX_ALIAS_EXPANSION} nodes through aliases)`);
1577
1653
  return { root, errors, duplicates };
1578
1654
  }
1579
1655
  function toJS(node) {
@@ -1680,6 +1756,38 @@ function isFreeForm(fqcnOrName) {
1680
1756
  }
1681
1757
  return FREE_FORM.has(parts[parts.length - 1]);
1682
1758
  }
1759
+ var CHECK_RAW_MODULES = /* @__PURE__ */ new Set(["command", "raw", "script", "shell", "win_command", "win_shell"]);
1760
+ var CHECK_RAW_OPTIONS = /* @__PURE__ */ new Set([
1761
+ "creates",
1762
+ "removes",
1763
+ "chdir",
1764
+ "executable",
1765
+ "warn",
1766
+ "stdin",
1767
+ "stdin_add_newline",
1768
+ "strip_empty_ends"
1769
+ ]);
1770
+ function isCheckRawAction(action) {
1771
+ const parts = action.split(".");
1772
+ if (parts.length === 1) return CHECK_RAW_MODULES.has(action);
1773
+ if (parts.length !== 3) return false;
1774
+ if (parts[0] === "ansible" && (parts[1] === "builtin" || parts[1] === "legacy"))
1775
+ return CHECK_RAW_MODULES.has(parts[2]);
1776
+ return parts[0] === "ansible" && parts[1] === "windows" && /^win_(command|shell)$/.test(parts[2]);
1777
+ }
1778
+ var IMPORT_PLAYBOOK_KEYS = [
1779
+ "import_playbook",
1780
+ "ansible.builtin.import_playbook",
1781
+ "ansible.legacy.import_playbook"
1782
+ ];
1783
+ var isPlayKey = (k) => k === "hosts" || IMPORT_PLAYBOOK_KEYS.includes(k);
1784
+ function importPlaybookEntry(play) {
1785
+ if (play.kind !== "map") return void 0;
1786
+ for (let i = play.entries.length - 1; i >= 0; i--) {
1787
+ if (IMPORT_PLAYBOOK_KEYS.includes(play.entries[i].key)) return play.entries[i].value;
1788
+ }
1789
+ return void 0;
1790
+ }
1683
1791
  var INCLUDE_TASKS = /* @__PURE__ */ new Set(["include_tasks", "import_tasks", "include"]);
1684
1792
  var INCLUDE_ROLE = /* @__PURE__ */ new Set(["include_role", "import_role"]);
1685
1793
  var builtinName = (a) => a.replace(/^ansible\.(builtin|legacy)\./, "");
@@ -1731,7 +1839,7 @@ function unquote(v) {
1731
1839
  if (v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0]) return v.slice(1, -1);
1732
1840
  return v;
1733
1841
  }
1734
- function parseKv(s) {
1842
+ function parseKv(s, checkRaw = false) {
1735
1843
  const options = {};
1736
1844
  const raw = [];
1737
1845
  for (const tok of splitArgs(s)) {
@@ -1747,7 +1855,7 @@ function parseKv(s) {
1747
1855
  continue;
1748
1856
  }
1749
1857
  const k = tok.slice(0, pos).trim();
1750
- if (/["']/.test(k)) {
1858
+ if (/["']/.test(k) || checkRaw && !CHECK_RAW_OPTIONS.has(k)) {
1751
1859
  raw.push(tok);
1752
1860
  continue;
1753
1861
  }
@@ -1803,7 +1911,7 @@ function extractTask(map, file, doc, extra = {}) {
1803
1911
  if (v.kind === "scalar" && typeof v.value === "string") {
1804
1912
  const [mod, ...rest] = splitArgs(v.value);
1805
1913
  t.action = mod;
1806
- const kv = parseKv(rest.join(" "));
1914
+ const kv = parseKv(rest.join(" "), !!mod && isCheckRawAction(mod));
1807
1915
  t.form = "kv";
1808
1916
  t.args = Object.entries(kv).map(([k, val]) => ({ name: k, line: v.line, value: val }));
1809
1917
  } else if (v.kind === "map") {
@@ -1827,12 +1935,18 @@ function extractTask(map, file, doc, extra = {}) {
1827
1935
  } else if (actionNode.kind === "scalar" && actionNode.value !== null && actionNode.value !== void 0) {
1828
1936
  t.form = "kv";
1829
1937
  const text2 = typeof actionNode.value === "string" ? actionNode.value : String(actionNode.value);
1830
- t.args = Object.entries(parseKv(text2)).map(([k, val]) => ({ name: k, line: actionNode.line, value: val }));
1938
+ t.args = Object.entries(parseKv(text2, isCheckRawAction(t.action))).map(([k, val]) => ({
1939
+ name: k,
1940
+ line: actionNode.line,
1941
+ value: val
1942
+ }));
1831
1943
  }
1832
1944
  }
1833
1945
  const argsKw = get(map, "args");
1834
1946
  if (argsKw?.kind === "map") {
1947
+ const own = new Set(t.args.map((a) => a.name));
1835
1948
  for (const e of argsKw.entries) {
1949
+ if (own.has(e.key)) continue;
1836
1950
  t.args = t.args.filter((a) => a.name !== e.key);
1837
1951
  t.args.push(entryArg(e.key, e.keyLine, e.value));
1838
1952
  }
@@ -1875,11 +1989,11 @@ function tasksOf(seq, file, doc, extra = {}) {
1875
1989
  }
1876
1990
  function isPlaybookRoot(root) {
1877
1991
  if (root?.kind !== "seq" || root.items.length === 0) return false;
1878
- return root.items.every(
1879
- (i) => i.kind === "map" && i.entries.some(
1880
- (e) => e.key === "hosts" || e.key === "import_playbook" || e.key === "ansible.builtin.import_playbook"
1881
- )
1882
- );
1992
+ return root.items.every((i) => i.kind === "map" && i.entries.some((e) => isPlayKey(e.key)));
1993
+ }
1994
+ function isPlaybookLike(root) {
1995
+ if (root?.kind !== "seq") return false;
1996
+ return root.items.some((i) => i.kind === "map" && i.entries.some((e) => isPlayKey(e.key)));
1883
1997
  }
1884
1998
  var MAX_YAML_BYTES = 2 * 1024 * 1024;
1885
1999
  var ProjectFiles = class {
@@ -1887,25 +2001,37 @@ var ProjectFiles = class {
1887
2001
  this.dir = dir;
1888
2002
  }
1889
2003
  dir;
2004
+ /** Per path: the parsed doc (null when unread), and the file size (undefined when not a readable file). */
1890
2005
  cache = /* @__PURE__ */ new Map();
2006
+ /** An absolute input is returned unchanged (a playbook outside dir); a relative one joins dir. */
1891
2007
  abs(rel) {
1892
- return join2(this.dir, rel);
2008
+ return isAbsolute(rel) ? rel : join2(this.dir, rel);
1893
2009
  }
2010
+ /** Relative to dir when inside it (drive-letter / case-insensitive on Windows), else the forward-slashed path. */
1894
2011
  rel(abs) {
1895
2012
  const a = abs.replace(/\\/g, "/");
1896
2013
  const b = this.dir.replace(/\\/g, "/").replace(/\/+$/, "");
1897
- return a.startsWith(`${b}/`) ? a.slice(b.length + 1) : a;
1898
- }
1899
- read(abs) {
1900
- if (this.cache.has(abs)) return this.cache.get(abs);
2014
+ const fold = (x) => process.platform === "win32" ? x.toLowerCase() : x;
2015
+ return fold(a).startsWith(fold(`${b}/`)) ? a.slice(b.length + 1) : a;
2016
+ }
2017
+ /** Parse a YAML file of at most `maxBytes` (default 2 MiB); null when missing, unreadable or larger. */
2018
+ read(abs, maxBytes = MAX_YAML_BYTES) {
2019
+ const hit = this.cache.get(abs);
2020
+ if (hit && (hit.size === void 0 || hit.size > maxBytes)) return null;
2021
+ if (hit?.doc) return hit.doc;
1901
2022
  let doc = null;
2023
+ let size;
1902
2024
  try {
1903
2025
  const st = statSync2(abs);
1904
- if (st.isFile() && st.size <= MAX_YAML_BYTES) doc = parseYaml(readFileSync2(abs, "utf8"));
2026
+ if (st.isFile()) {
2027
+ size = st.size;
2028
+ if (st.size <= maxBytes) doc = parseYaml(readFileSync2(abs, "utf8"));
2029
+ }
1905
2030
  } catch {
1906
2031
  doc = null;
2032
+ size = void 0;
1907
2033
  }
1908
- this.cache.set(abs, doc);
2034
+ this.cache.set(abs, { doc, size });
1909
2035
  return doc;
1910
2036
  }
1911
2037
  };
@@ -2035,7 +2161,7 @@ function walkPlaybooks(files, playbooks, opts) {
2035
2161
  const rel = files.rel(abs);
2036
2162
  for (const play of root.items) {
2037
2163
  if (play.kind !== "map") continue;
2038
- const imp = get(play, "import_playbook") ?? get(play, "ansible.builtin.import_playbook");
2164
+ const imp = importPlaybookEntry(play);
2039
2165
  if (imp) {
2040
2166
  const target = scalarString(imp);
2041
2167
  if (target && !isTemplated(target)) {
@@ -2116,6 +2242,53 @@ function walkFiles(dir, depth, out, base = dir) {
2116
2242
  }
2117
2243
  }
2118
2244
  }
2245
+ var TREE_SKIP_DIRS = /* @__PURE__ */ new Set([".cache", ".git", ".hg", ".svn", ".tox"]);
2246
+ var TREE_MAX_ENTRIES = 2e5;
2247
+ function yamlFilesUnder(dir, maxEntries = TREE_MAX_ENTRIES) {
2248
+ const files = [];
2249
+ const realSeen = /* @__PURE__ */ new Set();
2250
+ let entriesSeen = 0;
2251
+ let incomplete;
2252
+ const walk = (d) => {
2253
+ if (incomplete) return;
2254
+ try {
2255
+ const real = realpathSync(d);
2256
+ if (realSeen.has(real)) return;
2257
+ realSeen.add(real);
2258
+ } catch {
2259
+ incomplete = `could not be fully listed (${d})`;
2260
+ return;
2261
+ }
2262
+ let entries;
2263
+ try {
2264
+ entries = readdirSync(d, { withFileTypes: true });
2265
+ } catch {
2266
+ incomplete = `could not be fully listed (${d})`;
2267
+ return;
2268
+ }
2269
+ for (const e of entries.sort((x, y) => x.name < y.name ? -1 : x.name > y.name ? 1 : 0)) {
2270
+ if (++entriesSeen > maxEntries) {
2271
+ incomplete = `has more than ${maxEntries} entries to pre-scan`;
2272
+ return;
2273
+ }
2274
+ const p = join2(d, e.name);
2275
+ let isDirEntry = e.isDirectory();
2276
+ let isFileEntry = e.isFile();
2277
+ if (e.isSymbolicLink()) {
2278
+ isDirEntry = isDir(p);
2279
+ isFileEntry = isFile(p);
2280
+ }
2281
+ if (isDirEntry) {
2282
+ if (!TREE_SKIP_DIRS.has(e.name)) walk(p);
2283
+ } else if (isFileEntry && /\.ya?ml$/i.test(e.name)) {
2284
+ files.push(p);
2285
+ }
2286
+ if (incomplete) return;
2287
+ }
2288
+ };
2289
+ walk(dir);
2290
+ return incomplete ? { files, incomplete } : { files };
2291
+ }
2119
2292
  function readCfgStatic(dir) {
2120
2293
  const p = join2(dir, "ansible.cfg");
2121
2294
  if (!isFile(p)) return {};
@@ -2305,7 +2478,7 @@ function checkValue(label, spec, v, line, node, out) {
2305
2478
  }
2306
2479
  const choices = choicesOf(spec);
2307
2480
  const elements = type === "list" ? spec.elements ?? null : null;
2308
- const items = elements && Array.isArray(v) ? v : [v];
2481
+ const items = type === "list" && Array.isArray(v) ? v : [v];
2309
2482
  if (choices && (type !== "list" || Array.isArray(v) || typeof v !== "object")) {
2310
2483
  const list = type === "list" && typeof v === "string" ? v.split(",").map((s) => s.trim()) : items;
2311
2484
  for (const item of list) {
@@ -2313,7 +2486,7 @@ function checkValue(label, spec, v, line, node, out) {
2313
2486
  if (choices.some((c) => c === item || String(c) === String(item))) continue;
2314
2487
  if (typeof item === "boolean" && raw && isYaml11BoolWord(raw)) {
2315
2488
  out.values.push(
2316
- `${where}: unquoted ${raw} is the boolean ${item} in YAML 1.1, not one of ${choices.map(String).join("|")}; quote it ("${raw}")`
2489
+ sensitive(label, spec, item) ? `${where}: an unquoted value is a boolean in YAML 1.1, not one of ${choices.map(String).join("|")}; quote it` : `${where}: unquoted ${raw} is the boolean ${item} in YAML 1.1, not one of ${choices.map(String).join("|")}; quote it ("${raw}")`
2317
2490
  );
2318
2491
  } else {
2319
2492
  out.values.push(`${where}: ${show(item)} is not one of ${choices.map(String).join("|")}`);
@@ -2328,13 +2501,16 @@ function checkValue(label, spec, v, line, node, out) {
2328
2501
  out.values.push(`${where}: expected ${type}, got ${err}${detail}`);
2329
2502
  return;
2330
2503
  }
2504
+ const hide = sensitive(label, spec, v);
2331
2505
  if (type === "str" && typeof v === "boolean" && raw && isYaml11BoolWord(raw)) {
2332
2506
  out.values.push(
2333
- `${where}: unquoted ${raw} becomes the boolean ${v} in YAML 1.1 (Ansible passes the string '${v ? "True" : "False"}'); quote it ("${raw}")`
2507
+ hide ? `${where}: an unquoted value becomes a boolean in YAML 1.1; quote it` : `${where}: unquoted ${raw} becomes the boolean ${v} in YAML 1.1 (Ansible passes the string '${v ? "True" : "False"}'); quote it ("${raw}")`
2334
2508
  );
2335
2509
  }
2336
2510
  if (type === "str" && typeof v === "number" && /^0[0-7]+$/.test(raw)) {
2337
- out.values.push(`${where}: unquoted ${raw} is the octal integer ${v} in YAML 1.1; quote it ("${raw}")`);
2511
+ out.values.push(
2512
+ hide ? `${where}: an unquoted value is an octal integer in YAML 1.1; quote it` : `${where}: unquoted ${raw} is the octal integer ${v} in YAML 1.1; quote it ("${raw}")`
2513
+ );
2338
2514
  }
2339
2515
  if (elements && Array.isArray(v)) {
2340
2516
  const sub2 = subOptionsOf(spec);
@@ -3040,7 +3216,7 @@ function renderLint(version2, issues, stderr, maxLocations, profile) {
3040
3216
  }
3041
3217
 
3042
3218
  // src/playbook.ts
3043
- import { readdirSync as readdirSync3 } from "fs";
3219
+ import { existsSync as existsSync4, readdirSync as readdirSync3 } from "fs";
3044
3220
  import { dirname as dirname2, join as join4 } from "path";
3045
3221
  var tagList = (s) => (s ?? "").replace(/^\[|\]$/g, "").split(",").map((x) => x.trim()).filter(Boolean);
3046
3222
  function parseListOutput(text2) {
@@ -3119,35 +3295,51 @@ function firstSentence(text2) {
3119
3295
  const i = text2.search(/\.\s+(?=[A-Z])/);
3120
3296
  return (i > 0 ? text2.slice(0, i) : text2).replace(/\.$/, "");
3121
3297
  }
3122
- var LOOKUP_RE = /lookup\s*\(|query\s*\(|\bq\s*\(|\bpipe\b/;
3298
+ var LOOKUP_RE = /\b(?:lookup|query|pipe)\b/;
3299
+ var Q_RE = /\bq\b/;
3300
+ function mentionsLookup(s) {
3301
+ if (LOOKUP_RE.test(s)) return true;
3302
+ const open = s.search(/\{[{%]/);
3303
+ return open >= 0 && Q_RE.test(s.slice(open));
3304
+ }
3305
+ var PRESCAN_MAX_BYTES = 32 * 1024 * 1024;
3123
3306
  function prescanPlaybook(files, rel) {
3124
3307
  const hits = [];
3125
3308
  const seen = /* @__PURE__ */ new Set();
3126
3309
  const visit = (abs) => {
3127
3310
  if (seen.has(abs)) return;
3128
3311
  seen.add(abs);
3129
- const root = files.read(abs)?.root;
3130
- if (root?.kind !== "seq") return;
3131
3312
  const file = files.rel(abs);
3313
+ const doc = files.read(abs, PRESCAN_MAX_BYTES);
3314
+ if (!doc) {
3315
+ hits.push({ file, line: 0, play: "", field: "", unreadable: "could not be read" });
3316
+ return;
3317
+ }
3318
+ if (doc.errors.some((e) => e.startsWith(ALIAS_LIMIT_ERROR))) {
3319
+ hits.push({ file, line: 0, play: "", field: "", unreadable: `could not be fully parsed (${ALIAS_LIMIT_ERROR})` });
3320
+ return;
3321
+ }
3322
+ const root = doc.root;
3323
+ if (root?.kind !== "seq") return;
3132
3324
  for (const play of root.items) {
3133
3325
  if (play.kind !== "map") continue;
3134
3326
  const nameNode = get(play, "name");
3135
3327
  const label = nameNode?.kind === "scalar" && typeof nameNode.value === "string" ? nameNode.value : `#${play.line}`;
3136
3328
  const check = (field, node) => {
3137
3329
  for (const s of strings(node)) {
3138
- if (LOOKUP_RE.test(s.value)) hits.push({ file, line: s.line, play: label, field });
3330
+ if (mentionsLookup(s.value)) hits.push({ file, line: s.line, play: label, field });
3139
3331
  }
3140
3332
  };
3141
3333
  check("name", nameNode);
3142
3334
  check("hosts", get(play, "hosts"));
3143
3335
  check("vars_files", get(play, "vars_files"));
3144
- const imp = get(play, "import_playbook") ?? get(play, "ansible.builtin.import_playbook");
3336
+ const imp = importPlaybookEntry(play);
3145
3337
  if (imp) {
3146
3338
  check("import_playbook", imp);
3147
3339
  const target = imp.kind === "scalar" && typeof imp.value === "string" ? imp.value : null;
3148
3340
  if (target && !isTemplated(target)) {
3149
3341
  const p = join4(dirname2(abs), target);
3150
- if (isFile(p)) visit(p);
3342
+ if (existsSync4(p)) visit(p);
3151
3343
  }
3152
3344
  }
3153
3345
  }
@@ -3155,6 +3347,29 @@ function prescanPlaybook(files, rel) {
3155
3347
  visit(files.abs(rel));
3156
3348
  return hits;
3157
3349
  }
3350
+ function prescanLintTargets(files, paths, maxEntries) {
3351
+ const hits = [];
3352
+ const seen = /* @__PURE__ */ new Set();
3353
+ const scanFile = (abs) => {
3354
+ if (seen.has(abs)) return;
3355
+ seen.add(abs);
3356
+ const doc = files.read(abs, PRESCAN_MAX_BYTES);
3357
+ if (doc && !doc.errors.some((e) => e.startsWith(ALIAS_LIMIT_ERROR)) && !isPlaybookLike(doc.root)) return;
3358
+ hits.push(...prescanPlaybook(files, abs));
3359
+ };
3360
+ for (const p of paths) {
3361
+ if (isDir(p)) {
3362
+ const walk = yamlFilesUnder(p, maxEntries);
3363
+ if (walk.incomplete) {
3364
+ hits.push({ file: files.rel(p), line: 0, play: "", field: "", unreadable: walk.incomplete });
3365
+ }
3366
+ for (const abs of walk.files) scanFile(abs);
3367
+ } else if (existsSync4(p)) {
3368
+ scanFile(p);
3369
+ }
3370
+ }
3371
+ return hits;
3372
+ }
3158
3373
  function strings(node) {
3159
3374
  if (!node) return [];
3160
3375
  if (node.kind === "scalar") return typeof node.value === "string" ? [{ value: node.value, line: node.line }] : [];
@@ -3163,7 +3378,7 @@ function strings(node) {
3163
3378
  }
3164
3379
  function prescanRefusal(hits) {
3165
3380
  const lines = hits.map(
3166
- (h) => `${h.file}:${h.line} play '${h.play}' has a lookup in '${h.field}'; Ansible would run it on this machine while parsing. Not run.`
3381
+ (h) => h.unreadable ? `${h.file} ${h.unreadable} for the lookup pre-scan; Ansible would parse it. Not run.` : `${h.file}:${h.line} play '${h.play}' has a lookup in '${h.field}'; Ansible would run it on this machine while parsing. Not run.`
3167
3382
  );
3168
3383
  lines.push("Set ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1 to allow.");
3169
3384
  return lines.join("\n");
@@ -3285,7 +3500,7 @@ function optionLines(opts, depth, descLen, defaults, warnings, ep, prefix) {
3285
3500
  const flags = [];
3286
3501
  if (o.required) flags.push("[required]");
3287
3502
  if (o.default !== void 0 && o.default !== null)
3288
- flags.push(o.no_log ? "[default: (no_log)]" : `[default: ${JSON.stringify(o.default)}]`);
3503
+ flags.push(o.no_log ? "[default: (no_log)]" : `[default: ${redactStandalone(o.default, name)}]`);
3289
3504
  const ch = choicesOf(o);
3290
3505
  if (ch) flags.push(`[choices: ${ch.map(String).join("|")}]`);
3291
3506
  if (o.no_log) flags.push("[no_log]");
@@ -3325,13 +3540,16 @@ function renderRole(r) {
3325
3540
  if (defaults) {
3326
3541
  const noLog = /* @__PURE__ */ new Set();
3327
3542
  const documented = /* @__PURE__ */ new Set();
3543
+ const red = new Redactor();
3328
3544
  for (const e of Object.values(specs)) {
3329
3545
  for (const [k, o] of Object.entries(e.options ?? {})) {
3330
3546
  documented.add(k);
3331
3547
  if (o.no_log) noLog.add(k);
3548
+ if (o.default === void 0 || o.default === null) continue;
3549
+ if (!o.no_log) red.learn(o.default, [k]);
3550
+ else if (typeof o.default === "string") red.addSecret(o.default);
3332
3551
  }
3333
3552
  }
3334
- const red = new Redactor();
3335
3553
  for (const [k, v] of Object.entries(defaults.values)) {
3336
3554
  if (noLog.has(k)) {
3337
3555
  if (typeof v === "string") red.addSecret(v);
@@ -3387,6 +3605,7 @@ function refuseDash(param, v) {
3387
3605
  function assertRelative(ctx, p, rel, what) {
3388
3606
  ctx.runner.assertLocal(rel);
3389
3607
  refuseDash(what, rel);
3608
+ refuseDash(what, normalize(rel.trim()));
3390
3609
  const abs = /^[A-Za-z]:[\\/]|^\//.test(rel) ? rel : join6(p.dir, rel);
3391
3610
  ctx.runner.assertLocal(abs);
3392
3611
  return abs;
@@ -3686,9 +3905,10 @@ async function roleInterface(ctx, x) {
3686
3905
  let specs = null;
3687
3906
  let source = "meta/argument_specs.yml";
3688
3907
  if (ctx.runner.available()) {
3908
+ const base = roleDir.replace(/[\\/]+$/, "").split(/[\\/]/).pop();
3909
+ refuseDash("role", base);
3689
3910
  try {
3690
3911
  const sideParent = await ctx.runner.toSide(dirname3(roleDir));
3691
- const base = roleDir.replace(/[\\/]+$/, "").split(/[\\/]/).pop();
3692
3912
  const r = await ctx.runSafe(p, "ansible-doc", ["--json", "-t", "role", "-r", sideParent, base]);
3693
3913
  if (r.code === 0) {
3694
3914
  specs = roleSpecsFromDocJson(r.stdout, base)?.specs ?? null;
@@ -3755,11 +3975,6 @@ ${redactText(graph.stderr.trim()).slice(0, 2048)}`
3755
3975
  for (const s of sources) bases.set(isDir(s) ? s : dirname3(s), "");
3756
3976
  bases.set(p.dir, "");
3757
3977
  const files = new ProjectFiles(p.dir);
3758
- const fb = renderVarsFilesFallback(
3759
- [...bases.keys()].map((b) => ({ base: b, label: files.rel(b) })),
3760
- (abs) => files.rel(abs),
3761
- red
3762
- );
3763
3978
  const env = { ANSIBLE_VARS_ENABLED: "none" };
3764
3979
  const r = await ctx.runSafe(
3765
3980
  p,
@@ -3769,23 +3984,32 @@ ${redactText(graph.stderr.trim()).slice(0, 2048)}`
3769
3984
  env
3770
3985
  }
3771
3986
  );
3772
- const out = [
3773
- `degraded: group_vars/host_vars merged by Ansible are unavailable because ${fb.vaulted.join(", ") || "a vars file"} ${fb.vaulted.length === 1 ? "is a whole-file vault" : "are whole-file vaults"} (ansible-mcp never supplies vault secrets); showing per-file contents instead, without precedence.`
3774
- ];
3987
+ let hv = null;
3775
3988
  if (r.code === 0) {
3776
3989
  try {
3777
3990
  const data = JSON.parse(r.stdout);
3778
- const hv = host ? { [host]: data } : data?._meta?.hostvars ?? {};
3991
+ hv = host ? { [host]: data } : data?._meta?.hostvars ?? {};
3779
3992
  learnAll(red, hv);
3780
- out.push("inventory-file vars only:");
3781
- for (const [h, vars] of Object.entries(hv)) {
3782
- if (varsMode === "names") out.push(` ${h}: ${Object.keys(vars).sort().join(" ") || "(none)"}`);
3783
- else {
3784
- out.push(` ${h}:`);
3785
- out.push(...renderHostVars(vars, red, " "));
3786
- }
3787
- }
3788
3993
  } catch {
3994
+ hv = null;
3995
+ }
3996
+ }
3997
+ const fb = renderVarsFilesFallback(
3998
+ [...bases.keys()].map((b) => ({ base: b, label: files.rel(b) })),
3999
+ (abs) => files.rel(abs),
4000
+ red
4001
+ );
4002
+ const out = [
4003
+ `degraded: group_vars/host_vars merged by Ansible are unavailable because ${fb.vaulted.join(", ") || "a vars file"} ${fb.vaulted.length === 1 ? "is a whole-file vault" : "are whole-file vaults"} (ansible-mcp never supplies vault secrets); showing per-file contents instead, without precedence.`
4004
+ ];
4005
+ if (hv) {
4006
+ out.push("inventory-file vars only:");
4007
+ for (const [h, vars] of Object.entries(hv)) {
4008
+ if (varsMode === "names") out.push(` ${h}: ${Object.keys(vars).sort().join(" ") || "(none)"}`);
4009
+ else {
4010
+ out.push(` ${h}:`);
4011
+ out.push(...renderHostVars(vars, red, " "));
4012
+ }
3789
4013
  }
3790
4014
  }
3791
4015
  out.push("group_vars / host_vars files:");
@@ -4023,15 +4247,24 @@ async function lintSummary(ctx, x) {
4023
4247
  if (x.profile && !PROFILES.includes(x.profile)) return `profile must be one of ${PROFILES.join(", ")}`;
4024
4248
  const p = await ctx.project(x.dir);
4025
4249
  const files = new ProjectFiles(p.dir);
4026
- const targets = (x.paths ?? []).map((rel) => {
4027
- const abs = assertRelative(ctx, p, rel, "paths");
4028
- return files.rel(abs);
4029
- });
4030
- const playbooks = targets.length ? targets.filter((t) => isPlaybookRoot(files.read(join6(p.dir, t))?.root ?? null)) : detectProject(p.dir).playbooks.map((pb) => pb.rel);
4031
- const hits = playbooks.flatMap((pb) => prescanPlaybook(files, pb));
4250
+ const targetAbs = (x.paths ?? []).map((rel) => assertRelative(ctx, p, rel, "paths"));
4251
+ const hits = prescanLintTargets(files, targetAbs.length ? targetAbs : [p.dir]);
4032
4252
  if (hits.length && !ctx.allowPlayLookups) return prescanRefusal(hits);
4033
4253
  ctx.runner.assertAvailable();
4034
- const args = ["--offline", "-f", "codeclimate", ...x.profile ? ["--profile", x.profile] : [], ...targets];
4254
+ const targets = [];
4255
+ for (const a of targetAbs) {
4256
+ const rel = files.rel(a);
4257
+ const target = rel === a.replace(/\\/g, "/") ? await ctx.runner.toSide(a) : rel;
4258
+ refuseDash("paths", target);
4259
+ targets.push(target);
4260
+ }
4261
+ const args = [
4262
+ "--offline",
4263
+ "-f",
4264
+ "codeclimate",
4265
+ ...x.profile ? ["--profile", x.profile] : [],
4266
+ ...targets.length ? ["--", ...targets] : []
4267
+ ];
4035
4268
  const [r, v] = await Promise.all([
4036
4269
  ctx.runSafe(p, "ansible-lint", args),
4037
4270
  ctx.quietEnv().then((env) => ctx.runner.run("ansible-lint", ["--version", "--offline"], { env })).catch(() => null)
@@ -4066,7 +4299,18 @@ function routingFor(rt, type, fqcn, collection) {
4066
4299
  const short = fqcn.startsWith(`${collection}.`) ? fqcn.slice(collection.length + 1) : fqcn;
4067
4300
  return t[short] ?? t[fqcn];
4068
4301
  }
4069
- var fmtDefault2 = (v) => typeof v === "string" ? `'${v}'` : JSON.stringify(v ?? null);
4302
+ function fmtDefault(v, name, noLog) {
4303
+ if (noLog) return NO_LOG;
4304
+ const r = redactStandalone(v ?? null, name);
4305
+ if (r.startsWith('"')) {
4306
+ try {
4307
+ const s = JSON.parse(r);
4308
+ if (typeof s === "string") return `'${s}'`;
4309
+ } catch {
4310
+ }
4311
+ }
4312
+ return r;
4313
+ }
4070
4314
  var fmtChoiceValue = (v) => typeof v === "string" ? v : JSON.stringify(v);
4071
4315
  function sensitive2(label, spec, v) {
4072
4316
  return spec.no_log === true || isSecretKey(label) || typeof v === "string" && hasSecretShape(v);
@@ -4148,7 +4392,12 @@ function diffOptions(inst, targ, args, prefix, push) {
4148
4392
  const dI = specI.default ?? null;
4149
4393
  const dT = specT.default ?? null;
4150
4394
  if (JSON.stringify(dI) !== JSON.stringify(dT)) {
4151
- push("BEHAVIOR CHANGE", `${prefix}${name} not set; default ${fmtDefault2(dI)} -> ${fmtDefault2(dT)}`, 7);
4395
+ const noLog = specI.no_log === true || specT.no_log === true;
4396
+ push(
4397
+ "BEHAVIOR CHANGE",
4398
+ `${prefix}${name} not set; default ${fmtDefault(dI, name, noLog)} -> ${fmtDefault(dT, name, noLog)}`,
4399
+ 7
4400
+ );
4152
4401
  }
4153
4402
  }
4154
4403
  }
@@ -4208,7 +4457,7 @@ function renderUpgrade(r) {
4208
4457
  lines.push(
4209
4458
  `upgrade ${r.collection} ${r.installedVersion} -> ${r.targetVersion} (${bumpKind(r.installedVersion, r.targetVersion)}${down}) for ${r.dirLabel}`
4210
4459
  );
4211
- const req = r.requiresAnsible ? `requires_ansible '${r.requiresAnsible}' ${r.requiresOk ? "ok" : "NOT satisfied"} (ansible-core ${r.core})` : "requires_ansible not declared";
4460
+ const req = !r.requiresAnsible ? "requires_ansible not declared" : r.requiresOk === void 0 ? `requires_ansible '${r.requiresAnsible}' could not evaluate (${r.requiresError ?? "unparseable"}; ansible-core ${r.core})` : `requires_ansible '${r.requiresAnsible}' ${r.requiresOk ? "ok" : "NOT satisfied"} (ansible-core ${r.core})`;
4212
4461
  lines.push(
4213
4462
  `target: ${req}; dependencies: ${r.dependencies.length ? r.dependencies.join(", ") : "none"}; ${r.cacheNote}`
4214
4463
  );
@@ -4264,6 +4513,8 @@ function renderUpgrade(r) {
4264
4513
  else verdict = "NO IMPACT on used modules";
4265
4514
  if (r.requiresAnsible && r.requiresOk === false) {
4266
4515
  verdict = `BLOCKED (requires_ansible '${r.requiresAnsible}' excludes ansible-core ${r.core})${verdict.startsWith("BREAKING") ? `; also ${verdict}` : ""}`;
4516
+ } else if (r.requiresAnsible && r.requiresOk === void 0) {
4517
+ verdict += "; requires_ansible not checked";
4267
4518
  }
4268
4519
  lines.push(`verdict: ${verdict}`);
4269
4520
  return lines.join("\n");
@@ -4352,6 +4603,7 @@ async function ensureTarget(ctx, p, collection, version2) {
4352
4603
  if (hit && hit.collection_info?.version === version2) return { dir: target, downloaded: false, manifest: hit };
4353
4604
  await ctx.runner.sideMkdirp(base);
4354
4605
  const tmp = ctx.runner.sideJoin(base, `.tmp-${version2}-${randomBytes2(4).toString("hex")}`);
4606
+ let stale;
4355
4607
  try {
4356
4608
  const r = await ctx.runSafe(
4357
4609
  p,
@@ -4369,16 +4621,22 @@ async function ensureTarget(ctx, p, collection, version2) {
4369
4621
  if (!m || m.collection_info?.version !== version2) {
4370
4622
  throw new Error(`ansible-galaxy installed ${collection} but MANIFEST.json does not say ${version2}.`);
4371
4623
  }
4372
- if (!await ctx.runner.sideRename(tmp, target)) {
4373
- const winner = await readManifest(ctx, target, collection);
4374
- if (!winner)
4375
- throw new Error(`could not move the downloaded ${collection} ${version2} into the cache at ${target}.`);
4376
- return { dir: target, downloaded: true, manifest: winner };
4624
+ if (await ctx.runner.sideRename(tmp, target)) return { dir: target, downloaded: true, manifest: m };
4625
+ const winner = await readManifest(ctx, target, collection);
4626
+ if (winner?.collection_info?.version === version2) return { dir: target, downloaded: true, manifest: winner };
4627
+ const aside = ctx.runner.sideJoin(base, `.tmp-stale-${randomBytes2(4).toString("hex")}`);
4628
+ if (await ctx.runner.sideRename(target, aside)) stale = aside;
4629
+ if (!stale || !await ctx.runner.sideRename(tmp, target)) {
4630
+ throw new Error(
4631
+ `could not move the downloaded ${collection} ${version2} into the cache at ${target} (it holds ${winner ? `a tree that says ${winner.collection_info?.version ?? "no version"}` : "no MANIFEST.json"}); remove that directory and retry.`
4632
+ );
4377
4633
  }
4378
4634
  return { dir: target, downloaded: true, manifest: m };
4379
4635
  } finally {
4380
4636
  await ctx.runner.sideRemoveTemp(tmp, root).catch(() => {
4381
4637
  });
4638
+ if (stale) await ctx.runner.sideRemoveTemp(stale, root).catch(() => {
4639
+ });
4382
4640
  }
4383
4641
  }
4384
4642
  function sweepStaleTempDirs(cacheDir, now = Date.now()) {
@@ -4434,7 +4692,7 @@ async function runUpgrade(ctx, x) {
4434
4692
  if (listRes.code !== 0)
4435
4693
  throw new Error(
4436
4694
  `ansible-galaxy collection list failed (exit ${listRes.code}):
4437
- ${listRes.stderr.trim().slice(0, 2048)}`
4695
+ ${redactText(listRes.stderr.trim()).slice(0, 2048)}`
4438
4696
  );
4439
4697
  const installedAll = byCollection(parseCollectionList(listRes.stdout), collectionsPaths);
4440
4698
  const eff = installedAll.get(collection)?.[0];
@@ -4557,11 +4815,13 @@ ${listRes.stderr.trim().slice(0, 2048)}`
4557
4815
  }
4558
4816
  );
4559
4817
  let requiresOk;
4818
+ let requiresError;
4560
4819
  if (targetRuntime.requiresAnsible) {
4561
4820
  try {
4562
4821
  requiresOk = satisfies(ver.core.replace(/[^\d.].*$/, ""), targetRuntime.requiresAnsible);
4563
- } catch {
4822
+ } catch (e) {
4564
4823
  requiresOk = void 0;
4824
+ requiresError = e instanceof Error ? e.message : String(e);
4565
4825
  }
4566
4826
  }
4567
4827
  const reqFiles = det.requirements.map((f) => {
@@ -4608,7 +4868,7 @@ ${listRes.stderr.trim().slice(0, 2048)}`
4608
4868
  targetVersion: version2,
4609
4869
  dirLabel: p.dir,
4610
4870
  core: ver.core,
4611
- ...targetRuntime.requiresAnsible ? { requiresAnsible: targetRuntime.requiresAnsible, requiresOk } : {},
4871
+ ...targetRuntime.requiresAnsible ? { requiresAnsible: targetRuntime.requiresAnsible, requiresOk, ...requiresError ? { requiresError } : {} } : {},
4612
4872
  dependencies: deps,
4613
4873
  cacheNote,
4614
4874
  constraints,