archgen-skill 0.1.1 → 0.1.2

package/lib/node_modules/archgen-mcp/src/core/docs.mjs

@@ -0,0 +1,178 @@
+// docs.mjs — markdown document model for doc-index.mjs: one implementation
+// shared by the digest index, the --section extractor and anchor validation.
+// Line ranges are 1-based post-CRLF normalization.
+
+/** Parse a markdown document: headings, fences, artifact-path references. */
+export function parseMarkdown(text) {
+  const lines = text.split('\n');
+  const headings = [];
+  const allHeadings = [];
+  const fences = [];
+  const links = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^ {0,3}```/.test(line)) {
+      const info = line.replace(/^ {0,3}```/, '').trim();
+      // CommonMark pairing: inside an open fence only a BARE ``` closes it —
+      // an info-carrying ``` is CONTENT, never an opener.
+      if (inFence) {
+        if (info === '') { fences.push({ line: i + 1, info: null }); inFence = false; }
+      } else {
+        fences.push({ line: i + 1, info });
+        inFence = true;
+      }
+      continue;
+    }
+    if (inFence) continue;
+    const h = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (h) {
+      const entry = { level: h[1].length, text: h[2], line: i + 1 };
+      allHeadings.push(entry);
+      if (entry.level <= 3) headings.push(entry);
+      continue;
+    }
+    ARTIFACT_PATH_RE.lastIndex = 0;
+    let m;
+    while ((m = ARTIFACT_PATH_RE.exec(line)) !== null) links.push({ line: i + 1, target: m[1] });
+    MD_LINK_RE.lastIndex = 0;
+    let lm;
+    while ((lm = MD_LINK_RE.exec(line)) !== null) {
+      const t = lm[1];
+      if (/^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith('#')) continue; // scheme'd or pure anchor
+      if (/\.(md|markdown|ya?ml)$/i.test(t.split('#')[0])) links.push({ line: i + 1, target: t });
+    }
+  }
+  // A target reachable by both extractors counts once.
+  const seen = new Set();
+  const uniqueLinks = links.filter((l) => {
+    const k = `${l.line}\u0000${l.target}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+  return { lines, headings, allHeadings, fences, links: uniqueLinks, balanced: fences.length % 2 === 0 };
+}
+
+// Artifact-relative cross-references: a slash-carrying path ending in a
+// doc/yaml extension, e.g. `../architecture.yaml`.
+const ARTIFACT_PATH_RE = /(?<![A-Za-z0-9_./-])((?:\.\.?\/)?[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.(?:md|markdown|ya?ml))(?![A-Za-z0-9_/-])/g;
+const MD_LINK_RE = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+/**
+ * GitHub-exact heading slug: lowercase, punctuation dropped, each whitespace
+ * char becomes a hyphen (runs are NOT collapsed: "TASK-02 — Auth API" ->
+ * "task-02--auth-api"). Hand-written anchors are GitHub anchors, so the
+ * slugger must match GitHub exactly.
+ */
+export function slugifyHeading(text) {
+  return String(text)
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+    .replace(/\s/g, '-');
+}
+
+/** Tolerant comparison: GitHub-exact plus the collapsed-hyphen variant. */
+function slugsMatch(a, b) {
+  if (a === b) return true;
+  const collapse = (s) => s.replace(/-{2,}/g, '-');
+  return collapse(a) === collapse(b);
+}
+
+/** Heading slugs incl. GitHub's -1/-2 duplicate disambiguation. */
+export function headingSlugs(doc) {
+  const map = new Map();
+  const counts = new Map();
+  for (const h of doc.allHeadings ?? []) {
+    const base = slugifyHeading(h.text);
+    if (!base) continue;
+    const n = counts.get(base) ?? 0;
+    counts.set(base, n + 1);
+    const slug = n === 0 ? base : `${base}-${n}`;
+    if (!map.has(slug)) map.set(slug, h);
+  }
+  return map;
+}
+
+/**
+ * Sections: a heading owns everything up to the next same-or-shallower
+ * heading (nested subsections included).
+ */
+export function buildSections(doc) {
+  const headings = doc.allHeadings ?? [];
+  const lines = doc.lines ?? [];
+  const counts = new Map();
+  const sections = [];
+  for (let i = 0; i < headings.length; i++) {
+    const h = headings[i];
+    const base = slugifyHeading(h.text);
+    if (!base) continue;
+    const n = counts.get(base) ?? 0;
+    counts.set(base, n + 1);
+    const slug = n === 0 ? base : `${base}-${n}`;
+    // End line: the line before the next heading at the same or shallower level.
+    let endLine = lines.length;
+    for (let j = i + 1; j < headings.length; j++) {
+      if (headings[j].level <= h.level) { endLine = headings[j].line - 1; break; }
+    }
+    const body = lines.slice(h.line - 1, endLine).join('\n');
+    sections.push({
+      level: h.level,
+      title: h.text,
+      slug,
+      line: h.line,
+      endLine,
+      body,
+    });
+  }
+  return sections;
+}
+
+/**
+ * Resolve a section by slug, title, tolerant slug variant, or PREFIX.
+ *
+ * The PREFIX form matters: the skill's `§` markers use SHORT names
+ * (`§artifact-templates/plan-depth`) while the headings produce longer
+ * slugs (`plan-depth-by-scope-class`). Every `§` shorthand in the skill is
+ * a prefix of a real slug, so accepting a prefix makes the shorthand the
+ * skill teaches actually RESOLVABLE — an agent can pass exactly what it was
+ * told without a discovery round-trip first.
+ *
+ * A prefix that matches MORE THAN ONE section is refused, never guessed:
+ * two sections sharing a prefix means the caller must use the full slug.
+ *
+ * @param {any} doc
+ * @param {string} ref
+ */
+export function findSection(doc, ref) {
+  const sections = buildSections(doc);
+  const wanted = String(ref).trim();
+  const bySlug = sections.find((s) => s.slug === wanted);
+  if (bySlug) return bySlug;
+  const bySlugLoose = sections.find((s) => s.slug === slugifyHeading(wanted));
+  if (bySlugLoose) return bySlugLoose;
+  const byTitle = sections.find((s) => s.title.toLowerCase() === wanted.toLowerCase());
+  if (byTitle) return byTitle;
+  // Case-insensitive + collapsed-hyphen comparison: agents type
+  // "FR-Catalog-01" or "fr-catalog-01" for the same heading.
+  const lower = wanted.toLowerCase();
+  const byLoose = sections.find((s) => slugsMatch(s.slug.toLowerCase(), lower));
+  if (byLoose) return byLoose;
+  // The `§` shorthand: a PREFIX of the slug. Only an UNAMBIGUOUS prefix
+  // resolves — a guess would send the agent to the wrong section.
+  const needle = slugifyHeading(wanted).toLowerCase();
+  if (!needle) return null;
+  const byPrefix = sections.filter((s) => s.slug.toLowerCase().startsWith(needle));
+  return byPrefix.length === 1 ? byPrefix[0] : null;
+}
+
+/** Does `anchor` exist in the target document? */
+export function anchorExists(targetDoc, anchor) {
+  const wanted = String(anchor).trim().toLowerCase();
+  if (!wanted) return false;
+  for (const slug of headingSlugs(targetDoc).keys()) {
+    if (slugsMatch(slug.toLowerCase(), wanted)) return true;
+  }
+  return false;
+}

package/lib/node_modules/archgen-mcp/src/core/errors.mjs

@@ -0,0 +1,65 @@
+// errors.mjs — the single error taxonomy for every archgen capability.
+//
+// Tool failures are DATA, not protocol errors: the agent must be able to read
+// a failure and act on it (fix the YAML, resolve the cycle, pass --force).
+// Protocol-level errors are reserved for malformed calls the SDK rejects
+// before a handler ever runs.
+//
+// The codes below are the stable contract. They map 1:1 onto the old script
+// exit codes so nothing that used to be scriptable stops being scriptable:
+//   2 -> CYCLE            (dependency cycle)
+//   3 -> OWNERSHIP_CONFLICT
+//   4 -> INVALID_INPUT    (usage / parse / IO)
+// plus the enterprise additions that the scripts never needed:
+//   NOT_FOUND · PERMISSION_DENIED · UNAVAILABLE · TIMEOUT · CONFLICT · INTERNAL
+
+/** @typedef {'INVALID_INPUT'|'NOT_FOUND'|'CYCLE'|'OWNERSHIP_CONFLICT'|'CONFLICT'|'PERMISSION_DENIED'|'UNAVAILABLE'|'TIMEOUT'|'INTERNAL'} ErrorCode */
+
+export class ArchgenError extends Error {
+  /**
+   * @param {ErrorCode} code
+   * @param {string} message
+   * @param {Record<string, unknown>} [details]
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'ArchgenError';
+    this.code = code;
+    this.details = details;
+  }
+
+  /** @returns {{code: ErrorCode, message: string, details: Record<string, unknown>}} */
+  toJSON() {
+    return { code: this.code, message: this.message, details: this.details };
+  }
+}
+
+/** Invalid usage, bad arguments, unparseable input. */
+export const invalidInput = (message, details) => new ArchgenError('INVALID_INPUT', message, details);
+/** A referenced path / task / document does not exist. */
+export const notFound = (message, details) => new ArchgenError('NOT_FOUND', message, details);
+/** The task graph contains a dependency cycle. */
+export const cycle = (message, details) => new ArchgenError('CYCLE', message, details);
+/** Two tasks in the same wave claim overlapping file ownership. */
+export const ownershipConflict = (message, details) => new ArchgenError('OWNERSHIP_CONFLICT', message, details);
+/** The action conflicts with current state (e.g. reopening a done task). */
+export const conflict = (message, details) => new ArchgenError('CONFLICT', message, details);
+/** A write was refused by a safety guard (symlink, outside-root, no approval). */
+export const permissionDenied = (message, details) => new ArchgenError('PERMISSION_DENIED', message, details);
+/** A required external actor is absent (a binary is missing, a service is down). */
+export const unavailable = (message, details) => new ArchgenError('UNAVAILABLE', message, details);
+/** An operation exceeded its deadline. */
+export const timeout = (message, details) => new ArchgenError('TIMEOUT', message, details);
+
+/**
+ * Normalize ANY thrown value into an ArchgenError. Unknown throws become
+ * INTERNAL but keep the original message — a stack trace never reaches the
+ * agent, but the cause always does.
+ * @param {unknown} e
+ * @returns {ArchgenError}
+ */
+export function toArchgenError(e) {
+  if (e instanceof ArchgenError) return e;
+  const message = e instanceof Error ? e.message : String(e);
+  return new ArchgenError('INTERNAL', message);
+}

package/lib/node_modules/archgen-mcp/src/core/fs-safety.mjs

@@ -0,0 +1,247 @@
+// fs-safety.mjs — filesystem primitives every write path must go through.
+//
+// WHY THIS EXISTS: the MCP server takes paths from a model. A model can be
+// talked into reading ~/.ssh, or into writing through a symlink that a
+// malicious clone shipped inside the repo. Every write therefore passes
+// through the same three gates:
+//
+//   1. assertNotSymlink  — lstat (never stat) the TARGET. A symlink is
+//      refused, never written through.
+//   2. assertWithinRoot  — resolve the REAL path (climbing to the nearest
+//      existing ancestor when the leaf does not exist yet, so a symlinked
+//      PARENT is caught too) and refuse anything that lands outside root.
+//   3. writeFileAtomic  — O_EXCL temp file + rename. Concurrent readers see
+//      old-or-new, never a half-written file. A crash before the rename
+//      leaves at worst an orphaned .tmp- sibling, never a corrupt original.
+//
+// These semantics are inherited verbatim from the CLI's store.js and from
+// skill/scripts/set-status.mjs — the MCP server must not be weaker than the
+// scripts it replaces.
+import { lstatSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { conflict, permissionDenied } from './errors.mjs';
+
+/** Canonical refusal message — identical wording to the CLI's. */
+export function refuseSymlinkMessage(absPath) {
+  return `Refusing to write through symlink at ${absPath} — remove the link or point it at a real directory`;
+}
+
+/**
+ * lstat (never stat — the LINK itself, not its target) a path before writing.
+ * Absent paths pass (safe to create); a symlink at the target throws.
+ * @param {string} absPath
+ */
+export function assertNotSymlink(absPath) {
+  let st = null;
+  try {
+    st = lstatSync(absPath);
+  } catch {
+    return;
+  }
+  if (st.isSymbolicLink()) throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath });
+}
+
+/**
+ * The REAL path of a path, climbing to the nearest existing ancestor when
+ * the leaf does not exist yet — so a symlinked PARENT is caught too.
+ *
+ * Returns null when the chain cannot be resolved at all (a broken symlink,
+ * or a component that is not a directory).
+ *
+ * @param {string} abs
+ * @returns {string|null}
+ */
+function realPathWithTail(abs) {
+  const tail = [];
+  let probe = resolve(abs);
+  for (;;) {
+    try {
+      const real = realpathSync(probe);
+      return tail.length ? join(real, ...tail) : real;
+    } catch (e) {
+      if (!e || e.code !== 'ENOENT') return null;
+      const parent = dirname(probe);
+      if (parent === probe) return null;
+      tail.unshift(basename(probe));
+      probe = parent;
+    }
+  }
+}
+
+/**
+ * Realpath-escape guard: refuse anything that lands outside `rootAbs`.
+ *
+ * TWO COMPARISONS, AND THE PATH IS ALLOWED IF EITHER SAYS IT IS INSIDE.
+ *
+ *   1. LEXICAL — the caller's spelling against the root's spelling.
+ *   2. REAL — where the path actually LANDS against where the root actually
+ *      IS. This is the one that catches a symlinked PARENT redirecting a
+ *      write elsewhere, and it is the only one that can answer the question
+ *      when the two paths are spelled differently.
+ *
+ * They can disagree, and they DO whenever the root and the path are spelled
+ * differently — which is the NORMAL case on macOS (`/tmp`, `/var`) and for
+ * any symlinked project: `process.cwd()` is the REAL path while the caller
+ * passes the LOGICAL one.
+ *
+ * The old guard compared the LEXICAL path against the REAL root and refused
+ * on that mismatch, so a perfectly valid path inside the project was
+ * reported as "outside the project" — and the two names the SAME place. The
+ * real comparison is the one that can actually answer the question, and it
+ * must be allowed to.
+ *
+ * The guard does NOT fail open: if the real comparison cannot be made, the
+ * lexical one stands on its own, and a path outside the root by every
+ * measure we could make is always refused.
+ *
+ * @param {string} rootAbs
+ * @param {string} absPath
+ */
+export function assertWithinRoot(rootAbs, absPath) {
+  const root = resolve(rootAbs);
+  const abs = resolve(absPath);
+
+  const rootReal = realPathWithTail(root);
+  const pathReal = realPathWithTail(abs);
+
+  const lexicalInside = abs === root || abs.startsWith(root + sep);
+  const realInside =
+    rootReal && pathReal ? pathReal === rootReal || pathReal.startsWith(rootReal + sep) : null;
+
+  if (realInside === true || (realInside === null && lexicalInside)) return;
+
+  if (lexicalInside) {
+    // Lexically inside, but it lands somewhere else: a symlinked parent.
+    throw permissionDenied(refuseSymlinkMessage(absPath), { path: absPath, root: rootAbs });
+  }
+  throw permissionDenied(
+    `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
+    { path: absPath, root: rootAbs },
+  );
+}
+
+/**
+ * Resolve `candidate` against `rootAbs` and prove it stays inside.
+ * @param {string} rootAbs absolute root directory
+ * @param {string} candidate absolute or relative path
+ * @returns {string} the resolved absolute path
+ */
+export function containPath(rootAbs, candidate) {
+  const root = resolve(rootAbs);
+  const abs = resolve(root, candidate);
+  assertWithinRoot(root, abs);
+  return abs;
+}
+
+/**
+ * Atomically write `content` to `file`.
+ *
+ * The temp name carries pid + timestamp + attempt so two concurrent writers
+ * never collide, and O_EXCL ('wx') guarantees a stale leftover is never
+ * silently truncated and overwritten. The original file stays byte-intact
+ * until the rename lands.
+ *
+ * @param {string} file absolute target path
+ * @param {string|Buffer} content
+ * @param {{eol?: string, root?: string}} [opts] `root` adds a containment
+ *   check for the whole parent chain, so a symlinked PARENT cannot redirect
+ *   the write outside the tree.
+ */
+export function writeFileAtomic(file, content, opts = {}) {
+  mkdirSync(dirname(file), { recursive: true });
+  if (opts.root) assertWithinRoot(opts.root, file);
+  assertNotSymlink(file);
+  let tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      writeFileSync(tmp, content, { flag: 'wx' });
+      break;
+    } catch (e) {
+      if (e?.code === 'EEXIST' && attempt < 10) {
+        tmp = `${file}.tmp-${process.pid}-${Date.now()}-${attempt + 1}`;
+        continue;
+      }
+      throw e;
+    }
+  }
+  try {
+    renameSync(tmp, file); // atomic on POSIX: readers observe old-or-new, never partial
+  } catch (e) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* original intact; leftover tmp is harmless */
+    }
+    throw e;
+  }
+  return file;
+}
+
+/**
+ * Run `fn` while holding an exclusive lock on `file`.
+ *
+ * WHY. An atomic write stops a READER seeing a half-written file. It does
+ * not stop two WRITERS losing each other's work: worker A reads tasks.yaml,
+ * worker B reads the same bytes, A writes its status change, B writes its
+ * own from the stale snapshot — and A's change is gone. The parallel
+ * workers are separate processes by design, so the guard has to live on
+ * disk, not in memory.
+ *
+ * The lock is a sibling `<file>.lock` created with O_EXCL. A lock older than
+ * `staleMs` is a crashed holder's leftover and is broken. The lock is always
+ * released, including when `fn` throws.
+ *
+ * @param {string} file the file being mutated
+ * @param {() => any} fn
+ * @param {{timeoutMs?: number, staleMs?: number, pollMs?: number}} [opts]
+ * @returns {any} whatever `fn` returns
+ */
+export function withFileLock(file, fn, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  const staleMs = opts.staleMs ?? 30_000;
+  const pollMs = opts.pollMs ?? 50;
+  const lockPath = `${file}.lock`;
+  const deadline = Date.now() + timeoutMs;
+
+  mkdirSync(dirname(lockPath), { recursive: true });
+  for (;;) {
+    try {
+      writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      break;
+    } catch (e) {
+      if (e?.code !== 'EEXIST') throw e;
+      // A lock older than staleMs belongs to a holder that died.
+      try {
+        const age = Date.now() - statSync(lockPath).mtimeMs;
+        if (age > staleMs) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        continue; // the lock vanished between the EEXIST and the stat
+      }
+      if (Date.now() > deadline) {
+        throw conflict(`timed out after ${timeoutMs}ms waiting for the lock on ${file}`, { file, lockPath });
+      }
+      sleepSync(pollMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      unlinkSync(lockPath);
+    } catch {
+      /* the lock is already gone */
+    }
+  }
+}
+
+/** Block the current thread for `ms` milliseconds. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+
+