baller-maester 0.1.0

package/dist/index.js

@@ -0,0 +1,1819 @@
+import { existsSync, promises } from 'fs';
+import { readFile, mkdir, writeFile, rm, mkdtemp, readdir, cp, rename } from 'fs/promises';
+import { parseDocument, isMap } from 'yaml';
+import path, { resolve, dirname, relative, extname } from 'path';
+import { z } from 'zod';
+import { execFile as execFile$1 } from 'child_process';
+import { promisify } from 'util';
+import { simpleGit } from 'simple-git';
+import picomatch from 'picomatch';
+import matter from 'gray-matter';
+
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var STATE_VALUES = ["draft", "canon"];
+var StateSchema = z.enum(STATE_VALUES);
+var DEFAULT_STATE = "draft";
+function parseState(value) {
+  if (value === void 0 || value === null) return { kind: "absent" };
+  const raw = typeof value === "string" ? value : String(value);
+  if (raw.length === 0) return { kind: "absent" };
+  const result = StateSchema.safeParse(raw);
+  if (result.success) return { kind: "valid", value: result.data };
+  return { kind: "invalid", raw };
+}
+
+// src/schemas/citadel.ts
+var SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+var ENV_VAR_RE = /^[A-Z][A-Z0-9_]*$/;
+var URL_FORMS = [/^https:\/\/\S+$/i, /^ssh:\/\/\S+$/i, /^git@[^\s:]+:\S+$/, /^file:\/\/\S+$/i];
+function isValidGitUrl(url) {
+  if (/\s/.test(url)) return false;
+  return URL_FORMS.some((re) => re.test(url));
+}
+function isSafeRelativePath(value) {
+  if (value.length === 0) return false;
+  if (value.startsWith("/")) return false;
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) return false;
+  return true;
+}
+function isSafeIncludesEntry(value) {
+  if (value.length === 0 || /^\s+$/.test(value)) return false;
+  if (value.startsWith("/")) return false;
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) return false;
+  return true;
+}
+var AuthRefNoneSchema = z.object({
+  type: z.literal("none")
+}).strict();
+var AuthRefTokenSchema = z.object({
+  type: z.literal("token"),
+  envVar: z.string().min(1, "envVar is required for token auth").regex(ENV_VAR_RE, "envVar must be uppercase letters, digits, and underscores")
+}).strict();
+var AuthRefSchema = z.discriminatedUnion("type", [AuthRefNoneSchema, AuthRefTokenSchema]);
+var IncludesPathSchema = z.string().min(1).refine(
+  isSafeIncludesEntry,
+  "includes entry must be a repo-relative path or glob; no leading '/' and no '..'"
+);
+var IncludeEntryObjectSchema = z.object({
+  path: IncludesPathSchema,
+  state: StateSchema.optional()
+}).strict();
+var IncludeEntrySchema = z.union([IncludesPathSchema, IncludeEntryObjectSchema]);
+function normalizeIncludeEntry(entry) {
+  if (typeof entry === "string") return { path: entry };
+  if (entry.state === void 0) return { path: entry.path };
+  return { path: entry.path, state: entry.state };
+}
+var SourceSchema = z.object({
+  name: z.string().min(1).regex(SLUG_RE, "name must be a kebab-case slug starting with a letter or digit"),
+  url: z.string().refine(isValidGitUrl, "url must be https://, ssh://, or git@host:path"),
+  ref: z.string().min(1).optional(),
+  includes: z.array(IncludeEntrySchema).min(1, "includes must declare at least one entry when present").optional(),
+  auth: AuthRefSchema.optional(),
+  destination: z.string().min(1).refine(isSafeRelativePath, "destination must be a repo-relative path with no '..' segments").optional(),
+  description: z.string().min(1).optional(),
+  tags: z.array(z.string().min(1).regex(SLUG_RE, "tags must be slugs")).optional()
+}).strict();
+var DEFAULT_BASE_DIR = "citadel";
+function applyCombinedInvariants(data, ctx) {
+  if (data.sources.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "citadel must declare at least one source",
+      path: ["sources"]
+    });
+    return;
+  }
+  const baseDir = data.baseDir ?? DEFAULT_BASE_DIR;
+  const namesSeen = /* @__PURE__ */ new Map();
+  const destsSeen = /* @__PURE__ */ new Map();
+  for (let i = 0; i < data.sources.length; i++) {
+    const entry = data.sources[i];
+    if (!entry?.name) continue;
+    const priorIndex = namesSeen.get(entry.name);
+    if (priorIndex !== void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `duplicate name '${entry.name}' \u2014 also used by sources[${priorIndex}]`,
+        path: ["sources", i, "name"]
+      });
+    } else {
+      namesSeen.set(entry.name, i);
+    }
+    const resolved = entry.destination ? resolve("/_citadel_root_", entry.destination) : resolve("/_citadel_root_", baseDir, entry.name);
+    const prior = destsSeen.get(resolved);
+    if (prior !== void 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `destination collision: sources '${entry.name}' and '${prior.name}' (sources[${prior.index}]) both resolve to the same path`,
+        path: ["sources", i, "destination"]
+      });
+    } else {
+      destsSeen.set(resolved, { index: i, name: entry.name });
+    }
+  }
+}
+var CitadelConfigSchema = z.object({
+  schemaVersion: z.literal(1),
+  baseDir: z.string().min(1).refine(isSafeRelativePath, "baseDir must be a repo-relative path with no '..' segments").optional(),
+  sources: z.array(SourceSchema).optional().default([])
+}).strict().superRefine((data, ctx) => {
+  applyCombinedInvariants(data, ctx);
+});
+function isSafeRepoRelative(value) {
+  if (value.length === 0 || /^\s+$/.test(value)) return false;
+  if (value.startsWith("/")) return false;
+  if (value.split(/[\\/]+/).some((seg) => seg === "..")) return false;
+  return true;
+}
+var PublishedDocumentSchema = z.object({
+  path: z.string().min(1).refine(
+    isSafeRepoRelative,
+    "path must be a repo-relative file or glob; no leading '/' and no '..'"
+  ),
+  description: z.string().min(1).optional(),
+  category: z.string().min(1).regex(SLUG_RE, "category must be a kebab-case slug").optional(),
+  tags: z.array(z.string().min(1).regex(SLUG_RE, "tags must be slugs")).optional(),
+  state: StateSchema.optional()
+}).strict();
+var MaesterConfigSchema = z.object({
+  schemaVersion: z.literal(1),
+  documents: z.array(PublishedDocumentSchema).min(1, "at least one published document must be declared").superRefine((docs, ctx) => {
+    const seen = /* @__PURE__ */ new Map();
+    for (let i = 0; i < docs.length; i++) {
+      const p = docs[i]?.path;
+      if (!p) continue;
+      const prior = seen.get(p);
+      if (prior !== void 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `duplicate path '${p}' (also at index ${prior})`,
+          path: [i, "path"]
+        });
+      } else {
+        seen.set(p, i);
+      }
+    }
+  })
+}).strict();
+
+// src/core/errors.ts
+var MaesterError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, options) {
+    super(message);
+    this.name = "MaesterError";
+    this.code = code;
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+var ConfigError = class extends MaesterError {
+  filePath;
+  line;
+  column;
+  constructor(message, detail = {}) {
+    super("CONFIG_ERROR", message, detail.cause !== void 0 ? { cause: detail.cause } : {});
+    this.name = "ConfigError";
+    this.filePath = detail.filePath;
+    if (detail.line !== void 0) this.line = detail.line;
+    if (detail.column !== void 0) this.column = detail.column;
+  }
+};
+var AuthError = class extends MaesterError {
+  envVar;
+  constructor(envVar, message) {
+    super("AUTH_ERROR", message ?? `Environment variable ${envVar} is not set.`);
+    this.name = "AuthError";
+    this.envVar = envVar;
+  }
+};
+var RefNotFoundError = class extends MaesterError {
+  ref;
+  url;
+  constructor(ref, url, cause) {
+    super(
+      "REF_NOT_FOUND",
+      `ref \`${ref}\` not found on \`${url}\``,
+      cause !== void 0 ? { cause } : {}
+    );
+    this.name = "RefNotFoundError";
+    this.ref = ref;
+    this.url = url;
+  }
+};
+var DestinationBlockedError = class extends MaesterError {
+  destination;
+  constructor(destination, message) {
+    super("DESTINATION_BLOCKED", message);
+    this.name = "DestinationBlockedError";
+    this.destination = destination;
+  }
+};
+var CITADEL_CONFIG_FILENAME = "citadel.yaml";
+var MAESTER_CONFIG_FILENAME = "maester.yaml";
+var CACHE_DIR_NAME = ".maester";
+var CACHE_SUBDIR = ".maester/cache";
+function citadelConfigPath(repoRoot) {
+  return resolve(repoRoot, CITADEL_CONFIG_FILENAME);
+}
+function maesterConfigPath(repoRoot) {
+  return resolve(repoRoot, MAESTER_CONFIG_FILENAME);
+}
+function cachePathForSource(repoRoot, sourceName) {
+  return resolve(repoRoot, CACHE_SUBDIR, sourceName);
+}
+function defaultDestinationFor(repoRoot, sourceName, baseDir) {
+  return resolve(repoRoot, baseDir ?? DEFAULT_BASE_DIR, sourceName);
+}
+
+// src/core/config/loader.ts
+async function loadCitadelConfig(repoRoot) {
+  const path4 = citadelConfigPath(repoRoot);
+  if (!existsSync(path4)) {
+    throw new ConfigError(
+      "No citadel.yaml found at the repository root. Run `npx maester init` to create one.",
+      { filePath: path4 }
+    );
+  }
+  const raw = await readFile(path4, "utf8");
+  return parseAndValidate(raw, CitadelConfigSchema, path4);
+}
+async function loadMaesterConfig(repoRoot) {
+  const path4 = maesterConfigPath(repoRoot);
+  if (!existsSync(path4)) {
+    throw new ConfigError(
+      "No maester.yaml found at the repository root. Run `npx maester publish` to create one.",
+      { filePath: path4 }
+    );
+  }
+  const raw = await readFile(path4, "utf8");
+  return parseAndValidate(raw, MaesterConfigSchema, path4);
+}
+function parseAndValidate(raw, schema, filePath) {
+  const data = parseYaml(raw, filePath);
+  return runSchema(data, schema, filePath);
+}
+function parseYaml(raw, filePath) {
+  const doc = parseDocument(raw, { keepSourceTokens: false });
+  const yamlErrors = doc.errors;
+  if (yamlErrors.length > 0) {
+    const first = yamlErrors[0];
+    const pos = positionFromError(first, raw);
+    throw new ConfigError(`YAML parse error: ${first.message}`, {
+      filePath,
+      line: pos.line,
+      column: pos.column,
+      cause: first
+    });
+  }
+  return doc.toJS({ maxAliasCount: -1 });
+}
+function runSchema(data, schema, filePath) {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const where = issue?.path?.length ? ` at \`${issue.path.join(".")}\`` : "";
+    throw new ConfigError(`${filePath}: ${issue?.message ?? "validation failed"}${where}`, {
+      filePath,
+      cause: result.error
+    });
+  }
+  return result.data;
+}
+function positionFromError(err, raw) {
+  const pos = err.pos;
+  if (!pos) return { line: 1, column: 1 };
+  const offset = pos[0];
+  let line = 1;
+  let lastLineStart = 0;
+  for (let i = 0; i < offset && i < raw.length; i++) {
+    if (raw[i] === "\n") {
+      line++;
+      lastLineStart = i + 1;
+    }
+  }
+  return { line, column: offset - lastLineStart + 1 };
+}
+
+// src/core/auth/resolver.ts
+function resolveAuth(auth, env = process.env) {
+  if (!auth || auth.type === "none") return { type: "delegated" };
+  const value = env[auth.envVar];
+  if (value === void 0 || value.length === 0) {
+    throw new AuthError(
+      auth.envVar,
+      `${auth.envVar} is not set. Define it in your shell, .env loader, or CI secret manager before syncing.`
+    );
+  }
+  return { type: "token", value };
+}
+var execFile = promisify(execFile$1);
+var cachedCapabilities;
+async function detectGitCapabilities() {
+  if (cachedCapabilities) return cachedCapabilities;
+  const { stdout } = await execFile("git", ["--version"]);
+  const match = stdout.match(/git version (\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) {
+    cachedCapabilities = { version: stdout.trim(), supportsPartialClone: false };
+    return cachedCapabilities;
+  }
+  const major = Number(match[1] ?? 0);
+  const minor = Number(match[2] ?? 0);
+  const supportsPartialClone = major > 2 || major === 2 && minor >= 27;
+  cachedCapabilities = { version: `${major}.${minor}`, supportsPartialClone };
+  return cachedCapabilities;
+}
+async function shallowSparseClone(input) {
+  await mkdir(input.destination, { recursive: true });
+  const caps = await detectGitCapabilities();
+  const url = input.useTokenInUrl ? injectToken(input.url, input.useTokenInUrl) : input.url;
+  const git = simpleGit(input.destination);
+  if (caps.supportsPartialClone) {
+    const cloneArgs = ["--filter=blob:none", "--depth=1", "--no-checkout", "--sparse"];
+    if (input.ref) cloneArgs.push("--branch", input.ref);
+    try {
+      await git.clone(url, ".", cloneArgs);
+    } catch (err) {
+      if (input.ref && refNotFoundFromError(err)) {
+        throw new RefNotFoundError(input.ref, input.url, err);
+      }
+      throw err;
+    }
+  } else {
+    const cloneArgs = ["--depth=1"];
+    if (input.ref) cloneArgs.push("--branch", input.ref);
+    try {
+      await git.clone(url, ".", cloneArgs);
+    } catch (err) {
+      if (input.ref && refNotFoundFromError(err)) {
+        throw new RefNotFoundError(input.ref, input.url, err);
+      }
+      throw err;
+    }
+  }
+  return git;
+}
+async function setSparsePatterns(workDir, patterns) {
+  const git = simpleGit(workDir);
+  if (patterns.length === 0) {
+    await git.raw(["sparse-checkout", "disable"]);
+    return;
+  }
+  await git.raw(["sparse-checkout", "set", "--no-cone", ...patterns]);
+}
+async function checkoutRef(workDir, ref) {
+  const git = simpleGit(workDir);
+  try {
+    if (ref) await git.checkout(ref);
+    else await git.checkout(["HEAD"]);
+  } catch (err) {
+    if (ref && refNotFoundFromError(err)) {
+      throw new RefNotFoundError(ref, await tryReadOriginUrl(workDir), err);
+    }
+    throw err;
+  }
+  const sha = (await git.revparse(["HEAD"])).trim();
+  return sha;
+}
+async function fetchHead(workDir, ref) {
+  const git = simpleGit(workDir);
+  const args = ref ? ["--depth=1", "origin", ref] : ["--depth=1", "origin"];
+  try {
+    await git.fetch(args);
+  } catch (err) {
+    if (ref && refNotFoundFromError(err)) {
+      throw new RefNotFoundError(ref, await tryReadOriginUrl(workDir), err);
+    }
+    throw err;
+  }
+  await git.raw(["reset", "--hard", "FETCH_HEAD"]);
+  return (await git.revparse(["HEAD"])).trim();
+}
+async function clearWorktree(workDir) {
+  await rm(workDir, { recursive: true, force: true });
+}
+async function listRemoteRef(input) {
+  const url = input.useTokenInUrl ? injectToken(input.url, input.useTokenInUrl) : input.url;
+  const git = simpleGit();
+  const target = input.ref ?? "HEAD";
+  let output;
+  try {
+    output = await git.listRemote([url, target]);
+  } catch (err) {
+    throw new RefNotFoundError(target, input.url, err);
+  }
+  const sha = parseListRemoteOutput(output, target);
+  if (!sha) {
+    throw new RefNotFoundError(target, input.url);
+  }
+  return sha;
+}
+function parseListRemoteOutput(output, target) {
+  const lines = output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0) return void 0;
+  let primary;
+  let peeled;
+  for (const line of lines) {
+    const match = line.match(/^([0-9a-f]{40})\s+(\S+)$/);
+    if (!match) continue;
+    const sha = match[1];
+    const refName = match[2];
+    if (!sha || !refName) continue;
+    if (refName === target) {
+      primary = sha;
+      continue;
+    }
+    if (matchesRefName(refName, target)) {
+      primary = sha;
+    }
+    if (refName.endsWith("^{}") && matchesRefName(refName.slice(0, -3), target)) {
+      peeled = sha;
+    }
+  }
+  return peeled ?? primary;
+}
+function matchesRefName(refName, target) {
+  if (refName === target) return true;
+  if (refName === `refs/heads/${target}`) return true;
+  if (refName === `refs/tags/${target}`) return true;
+  if (refName === `refs/remotes/origin/${target}`) return true;
+  return false;
+}
+function refNotFoundFromError(err) {
+  const msg = err instanceof Error ? `${err.message}
+${err.stack ?? ""}` : String(err);
+  return /Remote branch .+ not found/i.test(msg) || /couldn't find remote ref/i.test(msg) || /not a tree/i.test(msg) || /unknown revision or path/i.test(msg);
+}
+function injectToken(url, token) {
+  if (!url.startsWith("https://")) return url;
+  const after = url.slice("https://".length);
+  return `https://x-access-token:${token}@${after}`;
+}
+async function tryReadOriginUrl(workDir) {
+  try {
+    const git = simpleGit(workDir);
+    const remotes = await git.getRemotes(true);
+    return remotes.find((r) => r.name === "origin")?.refs.fetch ?? "";
+  } catch {
+    return "";
+  }
+}
+var MAESTER_MANIFEST_FILENAME = "maester.yaml";
+async function fetchSource(entry, ctx) {
+  if (entry.includes && entry.includes.length > 0) {
+    const normalized = entry.includes.map(normalizeIncludeEntry);
+    return fetchWithExplicitIncludes(entry, ctx, normalized);
+  }
+  return fetchWithRemoteManifest(entry, ctx);
+}
+async function fetchWithRemoteManifest(entry, ctx) {
+  if (!ctx.cacheExists) {
+    await shallowSparseClone({
+      url: entry.url,
+      destination: ctx.cacheDir,
+      ref: entry.ref,
+      ...ctx.tokenForUrl ? { useTokenInUrl: ctx.tokenForUrl } : {}
+    });
+    await setSparsePatterns(ctx.cacheDir, [MAESTER_MANIFEST_FILENAME]);
+    await checkoutRef(ctx.cacheDir, entry.ref);
+  } else {
+    await fetchHead(ctx.cacheDir, entry.ref);
+  }
+  const discovery = await discoverManifestFromCache(ctx.cacheDir);
+  if (discovery.mode === "no-manifest") {
+    throw manifestError(entry.name, discovery.reason);
+  }
+  await setSparsePatterns(ctx.cacheDir, discovery.patterns);
+  const commitSha = await checkoutRef(ctx.cacheDir, entry.ref);
+  return {
+    name: entry.name,
+    cacheDir: ctx.cacheDir,
+    commitSha,
+    filterSet: discovery.patterns,
+    rules: discovery.rules,
+    warnings: []
+  };
+}
+async function fetchWithExplicitIncludes(entry, ctx, normalized) {
+  if (!ctx.cacheExists) {
+    await shallowSparseClone({
+      url: entry.url,
+      destination: ctx.cacheDir,
+      ref: entry.ref,
+      ...ctx.tokenForUrl ? { useTokenInUrl: ctx.tokenForUrl } : {}
+    });
+  } else {
+    await fetchHead(ctx.cacheDir, entry.ref);
+  }
+  const patterns = normalized.map((entry2) => entry2.path);
+  await setSparsePatterns(ctx.cacheDir, patterns);
+  const commitSha = await checkoutRef(ctx.cacheDir, entry.ref);
+  const matchedFileCount = await countMaterializedFiles(ctx.cacheDir);
+  const warnings = [];
+  if (matchedFileCount === 0) {
+    warnings.push({ type: "no-matches", name: entry.name, includes: patterns });
+  }
+  const rules = normalized.map(
+    (entry2) => entry2.state === void 0 ? { pattern: entry2.path } : { pattern: entry2.path, state: entry2.state }
+  );
+  return {
+    name: entry.name,
+    cacheDir: ctx.cacheDir,
+    commitSha,
+    filterSet: patterns,
+    rules,
+    warnings
+  };
+}
+function manifestError(name, reason) {
+  if (reason === "absent") {
+    return new MaesterError(
+      "MAESTER_MANIFEST_MISSING",
+      `source '${name}' does not publish a maester.yaml manifest at the configured ref. Sync will not fall back to the full tree \u2014 either add a maester.yaml to the source repo or declare an \`includes\` list on this source.`
+    );
+  }
+  return new MaesterError(
+    "MAESTER_MANIFEST_INVALID",
+    `source '${name}' publishes a maester.yaml that failed schema validation. Sync will not fall back to the full tree \u2014 fix the manifest in the source repo or declare an \`includes\` list on this source.`
+  );
+}
+async function discoverManifestFromCache(cacheDir) {
+  const path4 = resolve(cacheDir, MAESTER_MANIFEST_FILENAME);
+  if (!existsSync(path4)) return { mode: "no-manifest", reason: "absent" };
+  try {
+    const raw = await readFile(path4, "utf8");
+    const doc = parseDocument(raw);
+    if (doc.errors.length > 0) return { mode: "no-manifest", reason: "invalid" };
+    const parsed = MaesterConfigSchema.safeParse(doc.toJS({ maxAliasCount: -1 }));
+    if (!parsed.success) return { mode: "no-manifest", reason: "invalid" };
+    const rules = parsed.data.documents.map(
+      (d) => d.state === void 0 ? { pattern: d.path } : { pattern: d.path, state: d.state }
+    );
+    const patterns = parsed.data.documents.map((d) => d.path);
+    if (patterns.length === 0) return { mode: "no-manifest", reason: "invalid" };
+    if (!patterns.includes(MAESTER_MANIFEST_FILENAME)) patterns.unshift(MAESTER_MANIFEST_FILENAME);
+    return { mode: "manifest", patterns, rules };
+  } catch {
+    return { mode: "no-manifest", reason: "invalid" };
+  }
+}
+async function countMaterializedFiles(cacheDir) {
+  let count = 0;
+  async function walk2(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, {
+        withFileTypes: true,
+        encoding: "utf8"
+      });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === ".git") continue;
+      const fullPath = resolve(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk2(fullPath);
+      } else if (entry.isFile()) {
+        count++;
+      }
+    }
+  }
+  await walk2(cacheDir);
+  return count;
+}
+
+// src/core/state/html.ts
+var html_exports = {};
+__export(html_exports, {
+  parse: () => parse,
+  write: () => write
+});
+var STATE_COMMENT_RE = /^<!--\s*state:\s*([^\s-]+)\s*-->$/;
+function splitFirstLine(text) {
+  const crlfIdx = text.indexOf("\r\n");
+  const lfIdx = text.indexOf("\n");
+  if (crlfIdx !== -1 && (lfIdx === -1 || crlfIdx <= lfIdx)) {
+    return { firstLine: text.slice(0, crlfIdx), rest: text.slice(crlfIdx + 2), eol: "\r\n" };
+  }
+  if (lfIdx !== -1) {
+    return { firstLine: text.slice(0, lfIdx), rest: text.slice(lfIdx + 1), eol: "\n" };
+  }
+  return { firstLine: text, rest: "", eol: "\n" };
+}
+function parse(buf) {
+  const text = buf.toString("utf8");
+  const { firstLine } = splitFirstLine(text);
+  const match = firstLine.match(STATE_COMMENT_RE);
+  if (!match) return { kind: "absent" };
+  return parseState(match[1]);
+}
+function write(buf, state) {
+  const text = buf.toString("utf8");
+  const { firstLine, rest, eol } = splitFirstLine(text);
+  const desiredLine = `<!-- state: ${state} -->`;
+  const existingMatch = firstLine.match(STATE_COMMENT_RE);
+  if (existingMatch) {
+    if (firstLine === desiredLine) return buf;
+    return Buffer.from(`${desiredLine}${eol}${rest}`, "utf8");
+  }
+  const prefix = `${desiredLine}
+`;
+  return Buffer.from(`${prefix}${text}`, "utf8");
+}
+
+// src/core/state/json.ts
+var json_exports = {};
+__export(json_exports, {
+  parse: () => parse2,
+  write: () => write2
+});
+function detectIndent(text) {
+  const lines = text.split("\n");
+  for (const line of lines) {
+    if (line.startsWith("	")) return "	";
+    const match = line.match(/^( +)\S/);
+    if (match) return match[1]?.length ?? 2;
+  }
+  return 2;
+}
+function detectTrailingNewline(text) {
+  return text.endsWith("\n") ? "\n" : "";
+}
+function parse2(buf) {
+  let value;
+  try {
+    value = JSON.parse(buf.toString("utf8"));
+  } catch {
+    return { kind: "absent" };
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { kind: "absent" };
+  }
+  return parseState(value.state);
+}
+function write2(buf, state) {
+  const text = buf.toString("utf8");
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return buf;
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return buf;
+  }
+  const obj = value;
+  if (obj.state === state) return buf;
+  obj.state = state;
+  const indent = detectIndent(text);
+  const trailing = detectTrailingNewline(text);
+  const serialized = JSON.stringify(obj, null, indent);
+  return Buffer.from(`${serialized}${trailing}`, "utf8");
+}
+
+// src/core/state/markdown.ts
+var markdown_exports = {};
+__export(markdown_exports, {
+  parse: () => parse3,
+  write: () => write3
+});
+function parse3(buf) {
+  let parsed;
+  try {
+    parsed = matter(buf.toString("utf8"));
+  } catch {
+    return { kind: "absent" };
+  }
+  const raw = parsed.data.state;
+  return parseState(raw);
+}
+function write3(buf, state) {
+  let parsed;
+  try {
+    parsed = matter(buf.toString("utf8"));
+  } catch {
+    return buf;
+  }
+  const sourceData = parsed.data;
+  if (sourceData.state === state) return buf;
+  const nextData = { ...sourceData, state };
+  const next = matter.stringify(parsed.content, nextData);
+  return Buffer.from(next, "utf8");
+}
+
+// src/core/state/plaintext.ts
+var plaintext_exports = {};
+__export(plaintext_exports, {
+  parse: () => parse4,
+  write: () => write4
+});
+var STATE_LINE_RE = /^state:\s+(\S+)\s*$/;
+function splitFirstLine2(text) {
+  const crlfIdx = text.indexOf("\r\n");
+  const lfIdx = text.indexOf("\n");
+  if (crlfIdx !== -1 && (lfIdx === -1 || crlfIdx <= lfIdx)) {
+    return { firstLine: text.slice(0, crlfIdx), rest: text.slice(crlfIdx + 2), eol: "\r\n" };
+  }
+  if (lfIdx !== -1) {
+    return { firstLine: text.slice(0, lfIdx), rest: text.slice(lfIdx + 1), eol: "\n" };
+  }
+  return { firstLine: text, rest: "", eol: "\n" };
+}
+function parse4(buf) {
+  const text = buf.toString("utf8");
+  const { firstLine } = splitFirstLine2(text);
+  const match = firstLine.match(STATE_LINE_RE);
+  if (!match) return { kind: "absent" };
+  return parseState(match[1]);
+}
+function write4(buf, state) {
+  const text = buf.toString("utf8");
+  const { firstLine, rest, eol } = splitFirstLine2(text);
+  const desiredLine = `state: ${state}`;
+  const existingMatch = firstLine.match(STATE_LINE_RE);
+  if (existingMatch) {
+    if (firstLine === desiredLine) return buf;
+    return Buffer.from(`${desiredLine}${eol}${rest}`, "utf8");
+  }
+  return Buffer.from(`${desiredLine}
+${text}`, "utf8");
+}
+
+// src/core/state/yaml.ts
+var yaml_exports = {};
+__export(yaml_exports, {
+  parse: () => parse5,
+  write: () => write5
+});
+function parse5(buf) {
+  let doc;
+  try {
+    doc = parseDocument(buf.toString("utf8"));
+  } catch {
+    return { kind: "absent" };
+  }
+  if (doc.errors.length > 0) return { kind: "absent" };
+  if (!isMap(doc.contents)) return { kind: "absent" };
+  const raw = doc.get("state");
+  return parseState(raw);
+}
+function write5(buf, state) {
+  const text = buf.toString("utf8");
+  let doc;
+  try {
+    doc = parseDocument(text);
+  } catch {
+    return buf;
+  }
+  if (doc.errors.length > 0) return buf;
+  if (!isMap(doc.contents)) return buf;
+  if (doc.get("state") === state) return buf;
+  doc.set("state", state);
+  return Buffer.from(doc.toString(), "utf8");
+}
+
+// src/core/state/format.ts
+var HANDLERS = {
+  ".md": markdown_exports,
+  ".markdown": markdown_exports,
+  ".html": html_exports,
+  ".htm": html_exports,
+  ".yaml": yaml_exports,
+  ".yml": yaml_exports,
+  ".json": json_exports,
+  ".txt": plaintext_exports
+};
+function handlerFor(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  return HANDLERS[ext];
+}
+
+// src/core/state/applier.ts
+var MATCHER_OPTIONS = { dot: false, nocase: false };
+function compileMatchers(rules) {
+  return rules.map((r) => picomatch(r.pattern, MATCHER_OPTIONS));
+}
+function findRuleState(filePath, rules, matchers) {
+  for (let i = 0; i < rules.length; i++) {
+    const match = matchers[i];
+    const rule = rules[i];
+    if (!match || !rule) continue;
+    if (!match(filePath)) continue;
+    if (rule.state !== void 0) return rule.state;
+    return void 0;
+  }
+  return void 0;
+}
+async function* walk(dir, root) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true, encoding: "utf8" });
+  } catch {
+    return;
+  }
+  const isRoot = dir === root;
+  for (const entry of entries) {
+    if (entry.name === ".git") continue;
+    if (entry.name === ".maester-source.json") continue;
+    if (isRoot && entry.name === "maester.yaml") continue;
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(full, root);
+    } else if (entry.isFile()) {
+      yield relative(root, full);
+    }
+  }
+}
+async function applyState(stagedDir, rules) {
+  const matchers = compileMatchers(rules);
+  const breakdown = { canon: 0, draft: 0, untagged: 0 };
+  const warnings = [];
+  const details = [];
+  for await (const relPath of walk(stagedDir, stagedDir)) {
+    const handler = handlerFor(relPath);
+    if (!handler) {
+      breakdown.untagged++;
+      details.push({ file: relPath, state: "untagged", sourceOfTruth: "untagged" });
+      continue;
+    }
+    const fullPath = resolve(stagedDir, relPath);
+    const buf = await readFile(fullPath);
+    const parsed = handler.parse(buf);
+    let resolved;
+    let sourceOfTruth;
+    if (parsed.kind === "valid") {
+      resolved = parsed.value;
+      sourceOfTruth = "inline";
+      const ruleState = findRuleState(relPath, rules, matchers);
+      if (ruleState !== void 0 && ruleState !== resolved) {
+        warnings.push({
+          type: "disagreement",
+          file: relPath,
+          inline: resolved,
+          rule: ruleState
+        });
+      }
+    } else {
+      if (parsed.kind === "invalid") {
+        warnings.push({ type: "bad-inline-state", file: relPath, raw: parsed.raw });
+      }
+      const ruleState = findRuleState(relPath, rules, matchers);
+      if (ruleState !== void 0) {
+        resolved = ruleState;
+        sourceOfTruth = "rule";
+      } else {
+        resolved = DEFAULT_STATE;
+        sourceOfTruth = "default";
+      }
+    }
+    const next = handler.write(buf, resolved);
+    if (next !== buf) {
+      await writeFile(fullPath, next);
+    }
+    breakdown[resolved]++;
+    details.push({ file: relPath, state: resolved, sourceOfTruth });
+  }
+  return { breakdown, warnings, details };
+}
+var PROVENANCE_FILENAME = ".maester-source.json";
+async function writeProvenanceMarker(destination, marker) {
+  const path4 = resolve(destination, PROVENANCE_FILENAME);
+  const body = `${JSON.stringify(marker, null, 2)}
+`;
+  await writeFile(path4, body, "utf8");
+  return path4;
+}
+async function readProvenanceMarker(destination) {
+  const path4 = resolve(destination, PROVENANCE_FILENAME);
+  if (!existsSync(path4)) return void 0;
+  try {
+    const text = await readFile(path4, "utf8");
+    const parsed = JSON.parse(text);
+    if (typeof parsed.sourceName !== "string" || typeof parsed.sourceUrl !== "string" || typeof parsed.commitSha !== "string" || !Array.isArray(parsed.filterSet)) {
+      return void 0;
+    }
+    return {
+      sourceName: parsed.sourceName,
+      sourceUrl: parsed.sourceUrl,
+      ref: typeof parsed.ref === "string" ? parsed.ref : void 0,
+      commitSha: parsed.commitSha,
+      filterSet: parsed.filterSet,
+      syncedAt: typeof parsed.syncedAt === "string" ? parsed.syncedAt : (/* @__PURE__ */ new Date(0)).toISOString()
+    };
+  } catch {
+    return void 0;
+  }
+}
+function filterSetMatches(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+async function stageDestination(input) {
+  await assertDestinationSafe(input.destination, input.marker.sourceName);
+  const tempDir = `${input.destination}.tmp-${Math.random().toString(36).slice(2, 10)}`;
+  await mkdir(dirname(input.destination), { recursive: true });
+  await mkdir(tempDir, { recursive: true });
+  await copyCacheToTemp(input.cacheDir, tempDir);
+  const beforePromoteResult = input.beforePromote ? await input.beforePromote(tempDir) : void 0;
+  await writeProvenanceMarker(tempDir, input.marker);
+  await promoteTempToDestination(tempDir, input.destination);
+  if (beforePromoteResult !== void 0) {
+    return { staged: true, finalPath: input.destination, beforePromoteResult };
+  }
+  return { staged: true, finalPath: input.destination };
+}
+async function copyCacheToTemp(cacheDir, tempDir) {
+  if (!existsSync(cacheDir)) return;
+  const entries = await readdir(cacheDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === ".git") continue;
+    const src = resolve(cacheDir, entry.name);
+    const dst = resolve(tempDir, entry.name);
+    await cp(src, dst, { recursive: true, force: true, errorOnExist: false });
+  }
+}
+async function promoteTempToDestination(tempDir, destination) {
+  if (existsSync(destination)) {
+    const backup = `${destination}.old-${Math.random().toString(36).slice(2, 10)}`;
+    await rename(destination, backup);
+    try {
+      await rename(tempDir, destination);
+    } catch (err) {
+      await rename(backup, destination).catch(() => void 0);
+      throw err;
+    }
+    await rm(backup, { recursive: true, force: true });
+    return;
+  }
+  await rename(tempDir, destination);
+}
+async function assertDestinationSafe(destination, expectedSourceName) {
+  if (!existsSync(destination)) return;
+  const entries = await readdir(destination);
+  if (entries.length === 0) return;
+  if (entries.length === 1 && entries[0] === PROVENANCE_FILENAME) {
+    const marker2 = await readProvenanceMarker(destination);
+    if (!marker2 || marker2.sourceName === expectedSourceName) return;
+  }
+  const marker = await readProvenanceMarker(destination);
+  if (marker && marker.sourceName === expectedSourceName) return;
+  throw new DestinationBlockedError(
+    destination,
+    `Refusing to overwrite ${destination}: contains content that was not produced by '${expectedSourceName}'. Remove the directory or choose a different destination.`
+  );
+}
+
+// src/core/sync/runner.ts
+var DEFAULT_CONCURRENCY = 4;
+async function runSync(config, options) {
+  const env = options.env ?? process.env;
+  const scope = options.scope?.length ? new Set(options.scope) : void 0;
+  const baseDir = options.baseDir ?? config.baseDir;
+  if (scope) {
+    const known = new Set(config.sources.map((s) => s.name));
+    for (const name of scope) {
+      if (!known.has(name)) {
+        throw new MaesterError(
+          "UNKNOWN_SOURCE",
+          `Unknown source '${name}' \u2014 not declared in citadel.yaml.`
+        );
+      }
+    }
+  }
+  const entries = config.sources.filter((s) => !scope || scope.has(s.name));
+  const limit = Math.min(
+    Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY),
+    entries.length || 1
+  );
+  const outcomes = new Array(entries.length);
+  await mkdir(resolve(options.repoRoot, CACHE_SUBDIR), { recursive: true });
+  let cursor = 0;
+  const workers = [];
+  for (let i = 0; i < limit; i++) {
+    workers.push(
+      (async () => {
+        while (true) {
+          const index = cursor++;
+          if (index >= entries.length) return;
+          const entry = entries[index];
+          if (!entry) return;
+          outcomes[index] = await processEntry(entry, options, env, baseDir);
+        }
+      })()
+    );
+  }
+  await Promise.all(workers);
+  const failed = outcomes.filter((o) => o.status === "failed").length;
+  return { outcomes, failed };
+}
+async function processEntry(source, options, env, baseDir) {
+  const cacheDir = cachePathForSource(options.repoRoot, source.name);
+  const destination = source.destination ? resolve(options.repoRoot, source.destination) : defaultDestinationFor(options.repoRoot, source.name, baseDir);
+  options.onProgress?.({ type: "start", name: source.name });
+  try {
+    const auth = resolveAuth(source.auth, env);
+    const tokenForUrl = auth.type === "token" ? auth.value : void 0;
+    const cacheExists = existsSync(cacheDir);
+    const tree = await fetchSource(source, {
+      cacheDir,
+      cacheExists,
+      tokenForUrl
+    });
+    options.onProgress?.({ type: "fetched", name: source.name, commitSha: tree.commitSha });
+    for (const warning of tree.warnings) {
+      options.onProgress?.({ type: "warning", name: source.name, warning });
+    }
+    const existingMarker = await readProvenanceMarker(destination);
+    const wasUnchanged = !!existingMarker && existingMarker.commitSha === tree.commitSha && existingMarker.sourceName === source.name && filterSetMatches(existingMarker.filterSet, tree.filterSet) && existsSync(destination);
+    if (wasUnchanged) {
+      options.onProgress?.({ type: "staged", name: source.name, status: "unchanged" });
+      return {
+        name: source.name,
+        status: "unchanged",
+        destination,
+        ref: source.ref,
+        commitSha: tree.commitSha,
+        warnings: tree.warnings
+      };
+    }
+    const stageResult = await stageDestination({
+      cacheDir: tree.cacheDir,
+      destination,
+      marker: {
+        sourceName: tree.name,
+        sourceUrl: source.url,
+        ref: source.ref,
+        commitSha: tree.commitSha,
+        filterSet: tree.filterSet,
+        syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      beforePromote: (stagedDir) => applyState(stagedDir, tree.rules)
+    });
+    const stateResult = stageResult.beforePromoteResult;
+    const status = existingMarker ? "updated" : "added";
+    options.onProgress?.({ type: "staged", name: source.name, status });
+    return {
+      name: source.name,
+      status,
+      destination,
+      ref: source.ref,
+      commitSha: tree.commitSha,
+      warnings: tree.warnings,
+      ...stateResult ? {
+        stateBreakdown: stateResult.breakdown,
+        stateWarnings: stateResult.warnings,
+        stateDetails: stateResult.details
+      } : {}
+    };
+  } catch (err) {
+    const message = errorMessage(err);
+    options.onProgress?.({ type: "failed", name: source.name, error: message });
+    try {
+      await clearWorktree(cacheDir);
+    } catch {
+    }
+    return {
+      name: source.name,
+      status: "failed",
+      destination,
+      ref: source.ref,
+      warnings: [],
+      error: message
+    };
+  }
+}
+function errorMessage(err) {
+  if (err instanceof AuthError) return err.message;
+  if (err instanceof RefNotFoundError) return err.message;
+  if (err instanceof MaesterError) return err.message;
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+var SHA_RE = /^[0-9a-f]{40}$/;
+var MAESTER_MANIFEST_FILENAME2 = "maester.yaml";
+var STATUS_TEMP_PREFIX = ".status-";
+async function probeCommitSha(source, ctx) {
+  if (source.ref && SHA_RE.test(source.ref)) {
+    return source.ref;
+  }
+  return listRemoteRef({
+    url: source.url,
+    ref: source.ref,
+    ...ctx.tokenForUrl ? { useTokenInUrl: ctx.tokenForUrl } : {}
+  });
+}
+async function probeManifest(source, ctx) {
+  const tempRoot = resolve(ctx.repoRoot, CACHE_DIR_NAME);
+  await mkdir(tempRoot, { recursive: true });
+  const tempDir = await mkdtemp(resolve(tempRoot, STATUS_TEMP_PREFIX));
+  try {
+    await shallowSparseClone({
+      url: source.url,
+      destination: tempDir,
+      ref: source.ref,
+      ...ctx.tokenForUrl ? { useTokenInUrl: ctx.tokenForUrl } : {}
+    });
+    await setSparsePatterns(tempDir, [MAESTER_MANIFEST_FILENAME2]);
+    await checkoutRef(tempDir, source.ref);
+    const discovery = await discoverManifestFromCache(tempDir);
+    if (discovery.mode === "no-manifest") {
+      throw manifestError2(source.name, discovery.reason);
+    }
+    return { filterSet: discovery.patterns };
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+function manifestError2(name, reason) {
+  if (reason === "absent") {
+    return new MaesterError(
+      "MAESTER_MANIFEST_MISSING",
+      `source '${name}' does not publish a maester.yaml manifest at the configured ref.`
+    );
+  }
+  return new MaesterError(
+    "MAESTER_MANIFEST_INVALID",
+    `source '${name}' publishes a maester.yaml that failed schema validation.`
+  );
+}
+
+// src/core/status/runner.ts
+var DEFAULT_CONCURRENCY2 = 4;
+async function runStatus(config, options) {
+  const env = options.env ?? process.env;
+  const scope = options.scope?.length ? new Set(options.scope) : void 0;
+  const baseDir = options.baseDir ?? config.baseDir;
+  if (scope) {
+    const known = new Set(config.sources.map((s) => s.name));
+    for (const name of scope) {
+      if (!known.has(name)) {
+        throw new MaesterError(
+          "UNKNOWN_SOURCE",
+          `Unknown source '${name}' \u2014 not declared in citadel.yaml.`
+        );
+      }
+    }
+  }
+  const entries = config.sources.filter((s) => !scope || scope.has(s.name));
+  if (entries.length === 0) {
+    return { outcomes: [], counts: { upToDate: 0, behind: 0, failed: 0 } };
+  }
+  const limit = Math.min(Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY2), entries.length);
+  const outcomes = new Array(entries.length);
+  let cursor = 0;
+  const workers = [];
+  for (let i = 0; i < limit; i++) {
+    workers.push(
+      (async () => {
+        while (true) {
+          const index = cursor++;
+          if (index >= entries.length) return;
+          const entry = entries[index];
+          if (!entry) return;
+          outcomes[index] = await checkSource(entry, options, env, baseDir);
+        }
+      })()
+    );
+  }
+  await Promise.all(workers);
+  const counts = { upToDate: 0, behind: 0, failed: 0 };
+  for (const outcome of outcomes) {
+    if (outcome.verdict === "up-to-date") counts.upToDate++;
+    else if (outcome.verdict === "behind") counts.behind++;
+    else counts.failed++;
+  }
+  return { outcomes, counts };
+}
+async function checkSource(source, options, env, baseDir) {
+  const destination = source.destination ? resolve(options.repoRoot, source.destination) : defaultDestinationFor(options.repoRoot, source.name, baseDir);
+  const marker = await readProvenanceMarker(destination);
+  if (!marker) {
+    return {
+      name: source.name,
+      verdict: "behind",
+      reasons: ["never-synced"]
+    };
+  }
+  try {
+    const auth = resolveAuth(source.auth, env);
+    const tokenForUrl = auth.type === "token" ? auth.value : void 0;
+    const probeCtx = { repoRoot: options.repoRoot, tokenForUrl };
+    const resolvedSha = await probeCommitSha(source, probeCtx);
+    const reasons = [];
+    if (resolvedSha !== marker.commitSha) {
+      reasons.push("remote-ref-advanced");
+    }
+    const isManifestDriven = !source.includes || source.includes.length === 0;
+    if (isManifestDriven) {
+      const { filterSet } = await probeManifest(source, probeCtx);
+      if (!filterSetsEqual(filterSet, marker.filterSet)) {
+        reasons.push("manifest-changed");
+      }
+    }
+    if (reasons.length === 0) {
+      return {
+        name: source.name,
+        verdict: "up-to-date",
+        commitSha: resolvedSha
+      };
+    }
+    return {
+      name: source.name,
+      verdict: "behind",
+      reasons,
+      commitSha: marker.commitSha,
+      resolvedSha
+    };
+  } catch (err) {
+    return {
+      name: source.name,
+      verdict: "failed",
+      error: errorMessage2(err)
+    };
+  }
+}
+function filterSetsEqual(a, b) {
+  const left = [...new Set(a)].sort();
+  const right = [...new Set(b)].sort();
+  if (left.length !== right.length) return false;
+  for (let i = 0; i < left.length; i++) {
+    if (left[i] !== right[i]) return false;
+  }
+  return true;
+}
+function errorMessage2(err) {
+  if (err instanceof AuthError) return err.message;
+  if (err instanceof RefNotFoundError) return err.message;
+  if (err instanceof MaesterError) return err.message;
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+// src/core/skill/managed-region.ts
+var BEGIN_MARKER_RE = /<!--\s*maester:skill:begin(?:\s+v=([^\s>]+))?\s*-->/;
+var END_MARKER_LITERAL = "<!-- maester:skill:end -->";
+function extractMarkdownRegion(text) {
+  const beginMatch = BEGIN_MARKER_RE.exec(text);
+  if (!beginMatch) return void 0;
+  const beginIdx = beginMatch.index;
+  const afterBegin = beginIdx + beginMatch[0].length;
+  const endIdx = text.indexOf(END_MARKER_LITERAL, afterBegin);
+  if (endIdx < 0) return void 0;
+  const suffixStart = endIdx + END_MARKER_LITERAL.length;
+  return {
+    prefix: text.slice(0, beginIdx),
+    suffix: text.slice(suffixStart),
+    version: beginMatch[1]
+  };
+}
+function replaceMarkdownRegion(existing, body, version, preambleWhenAbsent = "") {
+  const region = renderManagedRegion(body, version);
+  if (existing === void 0) {
+    if (preambleWhenAbsent.length === 0) {
+      return `${region}
+`;
+    }
+    return `${preambleWhenAbsent}${preambleWhenAbsent.endsWith("\n") ? "" : "\n"}${region}
+`;
+  }
+  const found = extractMarkdownRegion(existing);
+  if (!found) {
+    const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    return `${existing}${sep}${region}
+`;
+  }
+  return `${found.prefix}${region}${found.suffix}`;
+}
+function renderManagedRegion(body, version) {
+  const inner = body.endsWith("\n") ? body.slice(0, -1) : body;
+  return `<!-- maester:skill:begin v=${version} -->
+${inner}
+${END_MARKER_LITERAL}`;
+}
+function replaceJsonMaesterKey(existingText, maesterBlock) {
+  const parsed = existingText && existingText.trim().length > 0 ? JSON.parse(existingText) : {};
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("Expected .claude/settings.json to be a JSON object at the top level.");
+  }
+  const rebuilt = {};
+  let placed = false;
+  for (const [key, value] of Object.entries(parsed)) {
+    if (key === "maester") {
+      rebuilt[key] = maesterBlock;
+      placed = true;
+    } else {
+      rebuilt[key] = value;
+    }
+  }
+  if (!placed) {
+    rebuilt.maester = maesterBlock;
+  }
+  return `${JSON.stringify(rebuilt, null, 2)}
+`;
+}
+function readJsonMaesterKey(existingText) {
+  if (!existingText || existingText.trim().length === 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(existingText);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+  const block = parsed.maester;
+  if (typeof block !== "object" || block === null || Array.isArray(block)) return void 0;
+  return block;
+}
+
+// src/core/skill/templates/content/citadel-awareness.md
+var citadel_awareness_default = '## Citadel awareness\n\nThis repository is a **citadel** \u2014 it pulls curated documentation from multiple\nremote sources into a single tree, managed by the `maester` CLI.\n\n- The citadel\'s aggregated content lives under `{{baseDir}}/` at the repository\n  root. Each direct subdirectory of `{{baseDir}}/` corresponds to one remote\n  source declared in `citadel.yaml` (`{{baseDir}}/<source-name>/...`).\n- The configuration that declares those sources is in `citadel.yaml` at the\n  repository root. It names each source, the git remote it pulls from, and the\n  ref it pins to.\n- When answering questions about anything the citadel covers, prefer citing\n  files under `{{baseDir}}/` over external knowledge. Cite the file path\n  relative to the repository root so the user can open it.\n- Each materialized file may carry a `state` value in its frontmatter or\n  inline (see "State awareness" below). Surface that state alongside any\n  citation so the user knows whether the source is canonical or draft.\n';
+
+// src/core/skill/templates/content/freshness-awareness.md
+var freshness_awareness_default = '## Freshness awareness\n\nCitadel content can drift out of date when remote sources advance after the\nlast sync. The Grand Maester is **auto-sync directed**: when the citadel is\nbehind, refresh it before reading rather than relying on stale content.\n\n**Auto-sync policy**\n\nWhen you discover that the citadel is behind \u2014 either from the Claude Code\npre-read hook\'s `additionalContext` message, or from a manual run of\n`npx maester status` \u2014 follow these steps without prompting the user:\n\n1. Run `npx maester sync` to refresh every configured source.\n   - Exits 0 on success.\n   - Exits non-zero if any source failed (missing auth env var, ref typo,\n     network error). Report the failure to the user and proceed cautiously.\n2. **Invalidate the pre-read hook\'s debounce cache** so the next read\n   observes fresh state instead of the stale verdict captured before the\n   sync:\n   ```\n   rm -f .maester/.skill-cache.json\n   ```\n3. Proceed with the original read of the citadel file.\n\nYou do not need to ask the user before syncing. `maester sync` is read-only\nagainst the remote sources it pulls from; it only materializes content the\n`citadel.yaml` already declared. The same sync the user would run manually.\n\n**Don\'t loop on failures.** If `maester sync` fails (or the hook reports a\n`failed` verdict from `maester status`), do **not** retry sync repeatedly.\nSurface the failure to the user, proceed with the read, and flag that cited\ncontent may be stale.\n\n**Avoid redundant syncs within a session.** Once you have synced and\ninvalidated the cache, ignore any further "citadel is behind" messages that\narrive before you have done another citadel read \u2014 they are cached signals\ncaptured before your sync completed.\n\n**Manual status check**\n\n```\nnpx maester status\n```\n\nExit codes:\n\n- **`0`** \u2014 every source is up to date.\n- **`1`** \u2014 at least one source is behind (remote advanced, manifest\n  changed, or never-synced). Run the auto-sync policy above.\n- **`2`** \u2014 the status check itself failed. Surface to the user; proceed\n  with a caveat that staleness cannot be verified.\n\nFor machine-readable output, pass `--json` and parse the NDJSON stream on\nstdout. The final line contains `{ "type": "summary", "upToDate": N,\n"behind": N, "failed": N }`.\n\n**On Claude Code specifically**, a `PreToolUse` hook installed by\n`maester skill install` runs the status check automatically before any\n`Read`, `Glob`, or `Grep` targeting a path under `{{baseDir}}/`. The\nhook debounces (default 300s, override with `MAESTER_SKILL_STATUS_TTL`) so\nthe check does not run more than once per session for routine reads.\n';
+
+// src/core/skill/templates/content/state-awareness.md
+var state_awareness_default = '## State awareness (canon vs draft)\n\nEvery citadel file may declare a publication state of `canon` (authoritative)\nor `draft` (work-in-progress). The state lives **inline** in the file using\nthe format\'s native convention:\n\n- **Markdown / MDX (`.md`, `.mdx`)** \u2014 `state` field inside YAML frontmatter\n  at the top of the file:\n  ```\n  ---\n  state: canon\n  ---\n  ```\n- **HTML (`.html`, `.htm`)** \u2014 first-line HTML comment:\n  `<!-- state: canon -->`\n- **YAML / JSON (`.yaml`, `.yml`, `.json`)** \u2014 a top-level `state` key.\n- **Plain text (`.txt`)** \u2014 `state: canon` as the very first line.\n\nFiles without inline state default to `draft`.\n\n**Policy when answering from the citadel:**\n\n1. **Prefer `canon` files** as the authoritative source of truth. When a\n   `canon` file answers the question, cite it and stop there.\n2. **`draft` files are informational only.** Cite them when no `canon`\n   alternative exists, but mark the citation explicitly: "(draft \u2014 work in\n   progress)" alongside the file path so the user knows the source is not yet\n   stable.\n3. **Never mix the two without labeling.** If you draw from both canon and\n   draft files in one answer, separate the two and tell the user which fact\n   came from which kind of source.\n';
+
+// src/core/skill/templates/shells/claude-code.ts
+var SKILL_FRONTMATTER_DESCRIPTION = "Citadel-aware guidance for reading aggregated documentation under the citadel base directory. Prefers canon files over draft and runs maester status before substantial citadel reads.";
+function renderClaudeSkillBody(opts) {
+  return [
+    "# Grand Maester (Claude Code skill)",
+    "",
+    "Use this guidance whenever you read files under the citadel base directory",
+    `(\`${opts.baseDir}/\`) in this repository.`,
+    "",
+    interpolate(citadel_awareness_default, opts),
+    "",
+    interpolate(state_awareness_default, opts),
+    "",
+    interpolate(freshness_awareness_default, opts)
+  ].join("\n");
+}
+function renderClaudeSkillFile(body) {
+  return [
+    "---",
+    "name: grand-maester",
+    `description: ${SKILL_FRONTMATTER_DESCRIPTION}`,
+    "---",
+    "",
+    body
+  ].join("\n");
+}
+function buildClaudeMaesterBlock(version) {
+  return {
+    version,
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "Read|Glob|Grep",
+          hooks: [{ type: "command", command: "npx maester skill runtime preread" }]
+        }
+      ]
+    }
+  };
+}
+function interpolate(template, opts) {
+  return template.replace(/\{\{baseDir\}\}/g, opts.baseDir);
+}
+
+// src/core/skill/targets/claude-code.ts
+var SKILL_MD_PATH = ".claude/skills/grand-maester/SKILL.md";
+var SETTINGS_JSON_PATH = ".claude/settings.json";
+var claudeCodeTarget = {
+  id: "claude-code",
+  label: "Claude Code",
+  artifactPaths: [SKILL_MD_PATH, SETTINGS_JSON_PATH],
+  writerKey: "claude-code",
+  write: writeClaudeCode,
+  readInstalledVersion
+};
+async function writeClaudeCode(input) {
+  const skillResult = await writeSkillMd(input);
+  const settingsResult = await writeSettingsJson(input);
+  const action = combineActions(skillResult.action, settingsResult.action);
+  return {
+    action,
+    installedVersion: input.skillVersion
+  };
+}
+async function writeSkillMd(input) {
+  const filePath = path.join(input.repoRoot, SKILL_MD_PATH);
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existing = await readTextOrUndefined(filePath);
+  const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
+  const body = renderClaudeSkillBody({ baseDir: input.citadelBaseDir });
+  const managedRegion = replaceMarkdownRegion(void 0, body, input.skillVersion).trimEnd();
+  const fileContent = existing ? replaceMarkdownRegion(existing, body, input.skillVersion) : `${renderClaudeSkillFile(managedRegion)}
+`;
+  if (existing === fileContent) return { action: "unchanged" };
+  await promises.writeFile(filePath, fileContent, "utf8");
+  if (existing === void 0) return { action: "installed" };
+  if (previousVersion === void 0) return { action: "installed" };
+  return { action: "upgraded" };
+}
+async function writeSettingsJson(input) {
+  const filePath = path.join(input.repoRoot, SETTINGS_JSON_PATH);
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existing = await readTextOrUndefined(filePath);
+  const previousBlock = readJsonMaesterKey(existing);
+  const previousVersion = typeof previousBlock?.version === "string" ? previousBlock.version : void 0;
+  const block = buildClaudeMaesterBlock(input.skillVersion);
+  const next = replaceJsonMaesterKey(existing, block);
+  if (existing === next) return { action: "unchanged" };
+  await promises.writeFile(filePath, next, "utf8");
+  if (existing === void 0 || previousBlock === void 0) return { action: "installed" };
+  if (previousVersion !== input.skillVersion) return { action: "upgraded" };
+  return { action: "upgraded" };
+}
+async function readInstalledVersion(repoRoot) {
+  const skillPath = path.join(repoRoot, SKILL_MD_PATH);
+  const text = await readTextOrUndefined(skillPath);
+  if (!text) return void 0;
+  return extractMarkdownRegion(text)?.version;
+}
+async function readTextOrUndefined(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+function combineActions(a, b) {
+  if (a === "failed" || b === "failed") return "failed";
+  if (a === "installed" || b === "installed") return "installed";
+  if (a === "upgraded" || b === "upgraded") return "upgraded";
+  return "unchanged";
+}
+
+// src/core/skill/templates/shells/agents-md.ts
+var PREAMBLE = `# AGENTS.md
+
+This file contains agent instructions for working in this repository. The
+section between the maester managed-region markers is generated by
+\`maester skill install\` and refreshed by \`maester skill upgrade\`. Anything
+you write outside that region is preserved across upgrades.
+`;
+function renderAgentsMdBody(opts) {
+  return [
+    "# Grand Maester guidance",
+    "",
+    "This repository is set up to aggregate documentation from remote sources",
+    "into a local citadel. When you reason about citadel content, follow the",
+    "guidance below.",
+    "",
+    interpolate2(citadel_awareness_default, opts),
+    "",
+    interpolate2(state_awareness_default, opts),
+    "",
+    interpolate2(freshness_awareness_default, opts)
+  ].join("\n");
+}
+function agentsMdPreamble() {
+  return PREAMBLE;
+}
+function interpolate2(template, opts) {
+  return template.replace(/\{\{baseDir\}\}/g, opts.baseDir);
+}
+
+// src/core/skill/targets/agents-md-writer.ts
+var AGENTS_MD_ARTIFACT_PATH = "AGENTS.md";
+async function writeAgentsMd(input) {
+  const filePath = path.join(input.repoRoot, AGENTS_MD_ARTIFACT_PATH);
+  const existingText = await readTextOrUndefined2(filePath);
+  const previousVersion = existingText ? extractMarkdownRegion(existingText)?.version : void 0;
+  const body = renderAgentsMdBody({ baseDir: input.citadelBaseDir });
+  const next = replaceMarkdownRegion(existingText, body, input.skillVersion, agentsMdPreamble());
+  const action = decideAction(existingText, previousVersion, input.skillVersion, next);
+  if (action === "unchanged") {
+    return previousVersion !== void 0 ? { action, installedVersion: previousVersion } : { action };
+  }
+  await promises.writeFile(filePath, next, "utf8");
+  return { action, installedVersion: input.skillVersion };
+}
+async function readAgentsMdInstalledVersion(repoRoot) {
+  const filePath = path.join(repoRoot, AGENTS_MD_ARTIFACT_PATH);
+  const text = await readTextOrUndefined2(filePath);
+  if (!text) return void 0;
+  return extractMarkdownRegion(text)?.version;
+}
+async function readTextOrUndefined2(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+function decideAction(existing, previousVersion, newVersion, newContent) {
+  if (existing === void 0) return "installed";
+  if (existing === newContent) return "unchanged";
+  if (previousVersion === void 0) return "installed";
+  if (previousVersion !== newVersion) return "upgraded";
+  return "upgraded";
+}
+
+// src/core/skill/targets/codex.ts
+var codexTarget = {
+  id: "codex",
+  label: "Codex CLI",
+  artifactPaths: [AGENTS_MD_ARTIFACT_PATH],
+  writerKey: "agents-md",
+  write: writeAgentsMd,
+  readInstalledVersion: readAgentsMdInstalledVersion
+};
+
+// src/core/skill/templates/shells/cursor.ts
+var DESCRIPTION = "Citadel-aware guidance for reading aggregated documentation under the citadel base directory.";
+function renderCursorRuleBody(opts) {
+  return [
+    "# Grand Maester (Cursor rule)",
+    "",
+    "This rule applies when the user asks about content under the citadel",
+    `base directory (\`${opts.baseDir}/\`).`,
+    "",
+    interpolate3(citadel_awareness_default, opts),
+    "",
+    interpolate3(state_awareness_default, opts),
+    "",
+    interpolate3(freshness_awareness_default, opts)
+  ].join("\n");
+}
+function renderCursorRuleFile(body, opts) {
+  return [
+    "---",
+    `description: ${DESCRIPTION}`,
+    `globs: ["${opts.baseDir}/**/*"]`,
+    "alwaysApply: false",
+    "---",
+    "",
+    body
+  ].join("\n");
+}
+function interpolate3(template, opts) {
+  return template.replace(/\{\{baseDir\}\}/g, opts.baseDir);
+}
+
+// src/core/skill/targets/cursor.ts
+var CURSOR_RULE_PATH = ".cursor/rules/grand-maester.mdc";
+var cursorTarget = {
+  id: "cursor",
+  label: "Cursor",
+  artifactPaths: [CURSOR_RULE_PATH],
+  writerKey: "cursor",
+  write: writeCursor,
+  readInstalledVersion: readInstalledVersion2
+};
+async function writeCursor(input) {
+  const filePath = path.join(input.repoRoot, CURSOR_RULE_PATH);
+  await promises.mkdir(path.dirname(filePath), { recursive: true });
+  const existing = await readTextOrUndefined3(filePath);
+  const previousVersion = existing ? extractMarkdownRegion(existing)?.version : void 0;
+  const body = renderCursorRuleBody({ baseDir: input.citadelBaseDir });
+  const next = existing ? replaceMarkdownRegion(existing, body, input.skillVersion) : `${renderCursorRuleFile(
+    replaceMarkdownRegion(void 0, body, input.skillVersion).trimEnd(),
+    {
+      baseDir: input.citadelBaseDir
+    }
+  )}
+`;
+  const action = decideAction2(existing, previousVersion, input.skillVersion, next);
+  if (action === "unchanged") {
+    return previousVersion !== void 0 ? { action, installedVersion: previousVersion } : { action };
+  }
+  await promises.writeFile(filePath, next, "utf8");
+  return { action, installedVersion: input.skillVersion };
+}
+async function readInstalledVersion2(repoRoot) {
+  const filePath = path.join(repoRoot, CURSOR_RULE_PATH);
+  const text = await readTextOrUndefined3(filePath);
+  if (!text) return void 0;
+  return extractMarkdownRegion(text)?.version;
+}
+async function readTextOrUndefined3(filePath) {
+  try {
+    return await promises.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
+  }
+}
+function decideAction2(existing, previousVersion, newVersion, newContent) {
+  if (existing === void 0) return "installed";
+  if (existing === newContent) return "unchanged";
+  if (previousVersion === void 0) return "installed";
+  if (previousVersion !== newVersion) return "upgraded";
+  return "upgraded";
+}
+
+// src/core/skill/targets/generic.ts
+var genericTarget = {
+  id: "agents-md",
+  label: "Generic AGENTS.md",
+  artifactPaths: [AGENTS_MD_ARTIFACT_PATH],
+  writerKey: "agents-md",
+  write: writeAgentsMd,
+  readInstalledVersion: readAgentsMdInstalledVersion
+};
+
+// src/core/skill/targets/index.ts
+var REGISTRY = [
+  claudeCodeTarget,
+  codexTarget,
+  cursorTarget,
+  genericTarget
+];
+function listSkillTargets() {
+  return REGISTRY;
+}
+function getTarget(id) {
+  const found = REGISTRY.find((t) => t.id === id);
+  if (!found) {
+    throw new Error(
+      `Unknown skill target '${id}'. Supported: ${REGISTRY.map((t) => t.id).join(", ")}`
+    );
+  }
+  return found;
+}
+function dedupeTargets(targets) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const target of targets) {
+    const existing = groups.get(target.writerKey);
+    if (existing) {
+      existing.ids.push(target.id);
+      existing.labels.push(target.label);
+    } else {
+      groups.set(target.writerKey, {
+        writerKey: target.writerKey,
+        primary: target,
+        ids: [target.id],
+        labels: [target.label],
+        artifactPaths: target.artifactPaths
+      });
+    }
+  }
+  return [...groups.values()];
+}
+
+// package.json
+var package_default = {
+  version: "0.1.0"};
+var PACKAGE_VERSION = package_default.version;
+
+// src/core/skill/version.ts
+var SKILL_VERSION = PACKAGE_VERSION;
+
+// src/core/skill/runner.ts
+async function runSkillInstall(repoRoot, opts) {
+  if (opts.targets.length === 0) {
+    throw new Error("At least one target id must be supplied.");
+  }
+  const targets = opts.targets.map((id) => getTarget(id));
+  const groups = dedupeTargets(targets);
+  const outcomes = [];
+  for (const group of groups) {
+    const writeOutcome = await safeWrite(group.primary.write, {
+      repoRoot,
+      skillVersion: SKILL_VERSION,
+      citadelBaseDir: opts.citadelBaseDir
+    });
+    for (let i = 0; i < group.ids.length; i += 1) {
+      const idValue = group.ids[i];
+      const labelValue = group.labels[i];
+      if (idValue === void 0 || labelValue === void 0) continue;
+      outcomes.push({
+        id: idValue,
+        label: labelValue,
+        artifactPaths: group.artifactPaths,
+        action: writeOutcome.action,
+        ...writeOutcome.installedVersion !== void 0 ? { installedVersion: writeOutcome.installedVersion } : {},
+        ...writeOutcome.error !== void 0 ? { error: writeOutcome.error } : {}
+      });
+    }
+  }
+  return { outcomes, counts: countOutcomes(outcomes) };
+}
+async function runSkillUpgrade(repoRoot, opts) {
+  const installedGroups = await findInstalledGroups(repoRoot);
+  if (installedGroups.length === 0) {
+    return { outcomes: [], counts: countOutcomes([]) };
+  }
+  const outcomes = [];
+  for (const group of installedGroups) {
+    const installedVersion = await group.primary.readInstalledVersion(repoRoot);
+    const isOutdated = installedVersion !== SKILL_VERSION;
+    if (opts.check === true) {
+      const action = isOutdated ? "upgraded" : "unchanged";
+      for (let i = 0; i < group.ids.length; i += 1) {
+        const idValue = group.ids[i];
+        const labelValue = group.labels[i];
+        if (idValue === void 0 || labelValue === void 0) continue;
+        outcomes.push({
+          id: idValue,
+          label: labelValue,
+          artifactPaths: group.artifactPaths,
+          action,
+          ...installedVersion !== void 0 ? { installedVersion } : {}
+        });
+      }
+      continue;
+    }
+    const writeOutcome = await safeWrite(group.primary.write, {
+      repoRoot,
+      skillVersion: SKILL_VERSION,
+      citadelBaseDir: opts.citadelBaseDir
+    });
+    for (let i = 0; i < group.ids.length; i += 1) {
+      const idValue = group.ids[i];
+      const labelValue = group.labels[i];
+      if (idValue === void 0 || labelValue === void 0) continue;
+      outcomes.push({
+        id: idValue,
+        label: labelValue,
+        artifactPaths: group.artifactPaths,
+        action: writeOutcome.action,
+        ...writeOutcome.installedVersion !== void 0 ? { installedVersion: writeOutcome.installedVersion } : {},
+        ...writeOutcome.error !== void 0 ? { error: writeOutcome.error } : {}
+      });
+    }
+  }
+  return { outcomes, counts: countOutcomes(outcomes) };
+}
+async function runSkillStatus(repoRoot) {
+  const outcomes = [];
+  let upToDate = 0;
+  let outdated = 0;
+  let notInstalled = 0;
+  for (const target of listSkillTargets()) {
+    const installedVersion = await target.readInstalledVersion(repoRoot);
+    let state;
+    if (installedVersion === void 0) {
+      state = "not-installed";
+      notInstalled += 1;
+    } else if (installedVersion === SKILL_VERSION) {
+      state = "up-to-date";
+      upToDate += 1;
+    } else {
+      state = "outdated";
+      outdated += 1;
+    }
+    outcomes.push({
+      id: target.id,
+      label: target.label,
+      artifactPaths: target.artifactPaths,
+      state,
+      ...installedVersion !== void 0 ? { installedVersion } : {},
+      currentVersion: SKILL_VERSION
+    });
+  }
+  return {
+    outcomes,
+    counts: { upToDate, outdated, notInstalled }
+  };
+}
+async function safeWrite(write6, input) {
+  try {
+    return await write6(input);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { action: "failed", error: message };
+  }
+}
+async function findInstalledGroups(repoRoot) {
+  const targets = listSkillTargets();
+  const installed = [];
+  for (const target of targets) {
+    const installedVersion = await target.readInstalledVersion(repoRoot);
+    if (installedVersion !== void 0) installed.push(target);
+  }
+  return dedupeTargets(installed);
+}
+function countOutcomes(outcomes) {
+  let installed = 0;
+  let upgraded = 0;
+  let unchanged = 0;
+  let failed = 0;
+  for (const o of outcomes) {
+    if (o.action === "installed") installed += 1;
+    else if (o.action === "upgraded") upgraded += 1;
+    else if (o.action === "unchanged") unchanged += 1;
+    else if (o.action === "failed") failed += 1;
+  }
+  return { installed, upgraded, unchanged, failed };
+}
+
+export { AuthError, ConfigError, DestinationBlockedError, MaesterError, RefNotFoundError, SKILL_VERSION, listSkillTargets, loadCitadelConfig, loadMaesterConfig, runSkillInstall, runSkillStatus, runSkillUpgrade, runStatus, runSync };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map