@momentiq/dark-factory-cli 1.1.0 → 2.1.0

package/dist/commands/skills.js

@@ -0,0 +1,248 @@
+// `df skills install/list` — CLI surface for the bundled-skill installer.
+//
+// DFP #192: the OSS CLI owns the source-of-truth for skills that ship as
+// part of the Dark Factory adoption (chief-engineer-review,
+// chief-engineer-blitz, and any future ones). This subcommand renders the
+// bundled skill templates against the consumer's `darkfactory.yaml` and
+// writes the result to `.claude/skills/<name>/` in the consumer repo.
+//
+// Sub-subcommand pattern mirrors `df flow` — top-level `df skills` fans
+// out to `install` / `list` inside cmdSkills rather than registering each
+// at the top of cli.ts. Keeps the namespace grouped.
+//
+// CLI mirror of: `df_skills_install` + `df_skills_list` MCP tools (the
+// same `installSkill` / `listBundledSkills` core powers both).
+import { enabledSkillNames, loadDarkFactoryConfig, } from "../skills/config.js";
+import { installSkill, KNOWN_SKILLS, listBundledSkills, } from "../skills/install.js";
+const TOP_HELP = [
+    "df skills — install consumer-shape templated skills bundled with @momentiq/dark-factory-cli.",
+    "",
+    "Usage:",
+    "  df skills install <name>       Render + install one bundled skill.",
+    "  df skills install --all        Install every skill declared `enabled: true`",
+    "                                 in darkfactory.yaml.",
+    "  df skills list                 List bundled skills + their summaries.",
+    "  df skills --help, -h           Show this message.",
+    "",
+    "Install flags (df skills install):",
+    "  --force                        Overwrite a hand-edited rendered file",
+    "                                 (skipped by default — the renderer detects",
+    "                                 the absence of the GENERATED marker).",
+    "  --target-dir <path>            Override the install location",
+    "                                 (default: <cwd>/.claude/skills/<name>/).",
+    "  --json                         Print the install result as JSON.",
+    "",
+    "Bundled skills:",
+    ...KNOWN_SKILLS.map((s) => `  - ${s}`),
+    "",
+    "Consumer config: place `darkfactory.yaml` at the repo root to override the",
+    "rendered values (REPO_NAME, MANIFESTO_PATH, ADR_DIR, etc.). See the project",
+    "README for the schema.",
+    "",
+].join("\n");
+function parseInstallArgs(rest) {
+    let skillName;
+    let all = false;
+    let force = false;
+    let json = false;
+    let targetDir;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i] ?? "";
+        if (a === "--all") {
+            all = true;
+            continue;
+        }
+        if (a === "--force") {
+            force = true;
+            continue;
+        }
+        if (a === "--json") {
+            json = true;
+            continue;
+        }
+        if (a === "--target-dir") {
+            const next = rest[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                return { error: "--target-dir requires a value." };
+            }
+            targetDir = next;
+            i++;
+            continue;
+        }
+        if (a.startsWith("--target-dir=")) {
+            targetDir = a.slice("--target-dir=".length);
+            continue;
+        }
+        if (a.startsWith("--")) {
+            return { error: `unknown flag: ${a}` };
+        }
+        if (skillName === undefined) {
+            skillName = a;
+            continue;
+        }
+        return { error: `unexpected positional arg: ${a}` };
+    }
+    if (!all && skillName === undefined) {
+        return { error: "missing skill name (or --all). Run `df skills --help`." };
+    }
+    if (all && skillName !== undefined) {
+        return { error: "cannot pass both <name> and --all." };
+    }
+    const out = {
+        all,
+        force,
+        json,
+        ...(skillName !== undefined ? { skillName } : {}),
+        ...(targetDir !== undefined ? { targetDir } : {}),
+    };
+    return out;
+}
+function renderInstallTextSummary(r) {
+    const lines = [];
+    lines.push(`df skills install: ${r.skillName} v${r.manifestVersion} → ${r.files.length} file(s) processed`);
+    lines.push(`  config: ${r.configPath}${r.configIsDefault ? " (defaults — no darkfactory.yaml present)" : ""}`);
+    for (const f of r.files) {
+        if (f.action === "skipped") {
+            lines.push(`  ! ${f.relTarget} — SKIPPED (${f.reason ?? "skipped"})`);
+        }
+        else {
+            lines.push(`  - ${f.relTarget} — ${f.action}`);
+        }
+    }
+    if (r.resolvedVariables.length > 0) {
+        lines.push(`  variables resolved:`);
+        for (const v of r.resolvedVariables) {
+            // Truncate multi-line list values to first line + ellipsis for the
+            // text summary — full values are visible in --json.
+            const oneLine = v.value.includes("\n")
+                ? `${v.value.split("\n")[0]} … (${v.value.split("\n").length} lines)`
+                : v.value;
+            lines.push(`    {{${v.name}}} = ${oneLine}`);
+        }
+    }
+    return lines.join("\n");
+}
+async function cmdSkillsInstall(rest, io) {
+    if (rest.includes("--help") || rest.includes("-h")) {
+        io.stdout(TOP_HELP);
+        return 0;
+    }
+    const parsed = parseInstallArgs(rest);
+    if ("error" in parsed) {
+        io.stderr(`df skills install: ${parsed.error}\n`);
+        return 2;
+    }
+    const cwd = process.cwd();
+    let targetSkills;
+    if (parsed.all) {
+        // Reject --all + --target-dir at the CLI surface: every bundled skill
+        // targets SKILL.md, so a shared target-dir would have the second install
+        // overwrite the first. Surface a clear error so the consumer either drops
+        // --target-dir (gets the default per-skill .claude/skills/<name>/) or
+        // splits the invocations one-skill-at-a-time.
+        if (parsed.targetDir !== undefined) {
+            io.stderr(`df skills install: --all is incompatible with --target-dir (bundled skills share target filenames like SKILL.md, so a single dir would overwrite). Install each skill separately, or omit --target-dir to use the default <cwd>/.claude/skills/<name>/.\n`);
+            return 2;
+        }
+        const loaded = loadDarkFactoryConfig(cwd);
+        const enabled = enabledSkillNames(loaded.config);
+        if (enabled.length === 0) {
+            io.stderr(`df skills install: --all found no skills marked enabled: true in ${loaded.configPath} (${loaded.isDefault ? "no darkfactory.yaml present" : "present"}).\n`);
+            return 1;
+        }
+        const unknown = enabled.filter((name) => !KNOWN_SKILLS.includes(name));
+        if (unknown.length > 0) {
+            io.stderr(`df skills install: --all rejected — unknown skill name(s) in ${loaded.configPath}: ${unknown.join(", ")}. Known skills: ${KNOWN_SKILLS.join(", ")}.\n`);
+            return 2;
+        }
+        targetSkills = enabled;
+    }
+    else if (parsed.skillName !== undefined) {
+        targetSkills = [parsed.skillName];
+    }
+    else {
+        // Shouldn't be reachable — parseInstallArgs guards.
+        io.stderr(`df skills install: no skill named.\n`);
+        return 2;
+    }
+    const results = [];
+    let exitCode = 0;
+    for (const name of targetSkills) {
+        try {
+            const opts = {
+                cwd,
+                skillName: name,
+                force: parsed.force,
+                ...(parsed.targetDir !== undefined ? { targetDir: parsed.targetDir } : {}),
+            };
+            const r = installSkill(opts);
+            results.push(r);
+            // Non-fatal but worth surfacing: if any file was skipped (hand-edited
+            // without --force), exit code 3 so CI catches the partial install.
+            if (r.files.some((f) => f.action === "skipped")) {
+                exitCode = Math.max(exitCode, 3);
+            }
+        }
+        catch (err) {
+            io.stderr(`df skills install: ${err.message}\n`);
+            return 1;
+        }
+    }
+    if (parsed.json) {
+        io.stdout(`${JSON.stringify({ installed: results }, null, 2)}\n`);
+    }
+    else {
+        for (const r of results) {
+            io.stdout(`${renderInstallTextSummary(r)}\n`);
+        }
+        if (exitCode === 3) {
+            io.stdout(`\nNote: one or more files were skipped because they were hand-edited. Re-run with --force to overwrite.\n`);
+        }
+    }
+    return exitCode;
+}
+function cmdSkillsList(rest, io) {
+    if (rest.includes("--help") || rest.includes("-h")) {
+        io.stdout(TOP_HELP);
+        return 0;
+    }
+    const json = rest.includes("--json");
+    const items = listBundledSkills();
+    if (json) {
+        io.stdout(`${JSON.stringify({ skills: items }, null, 2)}\n`);
+        return 0;
+    }
+    if (items.length === 0) {
+        io.stdout(`df skills list: no bundled skills.\n`);
+        return 0;
+    }
+    io.stdout(`df skills list — ${items.length} bundled skill(s)\n`);
+    for (const item of items) {
+        io.stdout(`\n  ${item.name} (v${item.version})`);
+        if (item.originatingRepo)
+            io.stdout(`  origin: ${item.originatingRepo}`);
+        io.stdout(`\n    ${item.summary}\n`);
+    }
+    return 0;
+}
+export async function cmdSkills(rest) {
+    const io = {
+        stdout: (s) => process.stdout.write(s),
+        stderr: (s) => process.stderr.write(s),
+    };
+    if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
+        io.stdout(TOP_HELP);
+        return 0;
+    }
+    const sub = rest[0];
+    const subRest = rest.slice(1);
+    if (sub === "install") {
+        return await cmdSkillsInstall(subRest, io);
+    }
+    if (sub === "list") {
+        return cmdSkillsList(subRest, io);
+    }
+    io.stderr(`df skills: unknown subcommand "${sub}". Run \`df skills --help\`.\n`);
+    return 2;
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"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"}

package/dist/cycle-doc-validator/validate_cycle_doc.py

@@ -134,7 +134,17 @@ def _resolve_repo_root() -> Path:
 
 
 REPO_ROOT = _resolve_repo_root()
+# Cycle-doc lookup paths in priority order. Legacy `docs/roadmap/cycles/` is
+# tried first for backward compatibility with sage3c / dark-factory-platform;
+# `docs/cycles/` is the newer dark-factory-dashboard convention (PR #105
+# moved it there to align with the eventual upstream convention). Consumers
+# that have moved to the new path get a working validator without
+# configuration; consumers still on the legacy path are unchanged.
+CYCLE_DOC_DIRS: tuple[str, ...] = ("docs/roadmap/cycles", "docs/cycles")
 CYCLES_DIR = REPO_ROOT / "docs" / "roadmap" / "cycles"
+# Glob and the singular `CYCLES_DIR` retained for backward compatibility with
+# downstream tooling that imports them. New code should prefer `CYCLE_DOC_DIRS`
+# + `_is_cycle_doc_path()` which check both layouts.
 CYCLE_DOC_GLOB = "docs/roadmap/cycles/cycle*.md"
 
 # Trailers we recognize. ``git-interpret-trailers`` defines a trailer as
@@ -238,14 +248,27 @@ def normalize_cycle_id(raw: str) -> str | None:
 
 
 def find_cycle_doc(cycle_id: str) -> CycleDoc | None:
-    """Locate ``docs/roadmap/cycles/cycle<id>*.md`` and read its status."""
-    matches = sorted(CYCLES_DIR.glob(f"cycle{cycle_id}-*.md")) + sorted(
-        CYCLES_DIR.glob(f"cycle{cycle_id}.md")
-    )
+    """Locate ``<cycle_dir>/cycle<id>*.md`` and read its status.
+
+    Searches every candidate dir in ``CYCLE_DOC_DIRS`` (legacy
+    ``docs/roadmap/cycles/`` first, then ``docs/cycles/``) so consumers
+    that have moved get a working lookup without configuration. If the
+    same cycle exists in both dirs (transitional state), prefers the
+    longer-named match across all hits — same disambiguation rule as
+    before, just over a wider candidate set.
+    """
+    matches: list[Path] = []
+    for cycle_dir in CYCLE_DOC_DIRS:
+        dir_path = REPO_ROOT / cycle_dir
+        if not dir_path.exists():
+            continue
+        matches.extend(sorted(dir_path.glob(f"cycle{cycle_id}-*.md")))
+        matches.extend(sorted(dir_path.glob(f"cycle{cycle_id}.md")))
     if not matches:
         return None
-    # If multiple matches exist (legacy ``cycle318.md`` + new ``cycle318-foo.md``),
-    # prefer the one with the longer name (more descriptive slug).
+    # If multiple matches exist (legacy ``cycle318.md`` + new ``cycle318-foo.md``,
+    # or one in each layout), prefer the one with the longer name (more
+    # descriptive slug).
     path = max(matches, key=lambda p: len(p.name))
     status, superseded_by = read_cycle_frontmatter(path)
     return CycleDoc(path=path, status=status, superseded_by=superseded_by)
@@ -332,50 +355,89 @@ def base_cycle_doc(
     if gh_token:
         env["GH_TOKEN"] = gh_token
 
-    try:
-        listing_result = subprocess.run(
-            [
-                "gh",
-                "api",
-                f"repos/{repo}/contents/docs/roadmap/cycles?ref={base_ref}",
-            ],
-            check=True,
-            capture_output=True,
-            text=True,
-            env=env,
-            timeout=60,
+    # Collect candidates across EVERY candidate cycle-doc dir on the base
+    # ref — DON'T break on the first successful listing. A consumer can
+    # have BOTH layouts present (transitional state — e.g. dark-factory-
+    # dashboard pre-#105 had cycle1-5 at legacy + cycle6 at the new path
+    # for one PR's worth of overlap), and a legacy dir that exists but
+    # lacks the cited cycle (sage3c with cycle331.x at legacy + a new
+    # cycle 6 at the new path) must fall through to the next dir. Per-dir
+    # 404 is the normal "consumer has not moved (or has moved fully) to
+    # this layout" signal; only fail if EVERY dir 404s or any dir hits a
+    # non-404 error.
+    pattern = re.compile(rf"^cycle{re.escape(cycle_id)}(?:-.+)?\.md$")
+    candidates: list[dict] = []
+    dirs_listed: list[str] = []
+    last_404: BaseCycleDocFetchError | None = None
+    for cycle_dir in CYCLE_DOC_DIRS:
+        try:
+            listing_result = subprocess.run(
+                [
+                    "gh",
+                    "api",
+                    f"repos/{repo}/contents/{cycle_dir}?ref={base_ref}",
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+                env=env,
+                timeout=60,
+            )
+        except FileNotFoundError as exc:
+            # gh CLI itself missing — environmental, fail loud regardless
+            # of which cycle_dir we were probing.
+            raise BaseCycleDocFetchError(
+                "gh CLI not on PATH; cannot read cycle docs from base ref."
+            ) from exc
+        except subprocess.CalledProcessError as exc:
+            # Treat 404 (or "not found") as "this dir doesn't exist on
+            # base ref; keep trying the others". Any other non-zero exit
+            # (auth, rate-limit, server error) escapes immediately —
+            # don't silently swallow a real failure as a missing-dir.
+            if _is_gh_not_found_error(exc):
+                last_404 = BaseCycleDocFetchError(
+                    f"gh api repos/{repo}/contents/{cycle_dir} returned 404 "
+                    f"(exit {exc.returncode}): {(exc.stderr or '').strip()}"
+                )
+                continue
+            raise BaseCycleDocFetchError(
+                f"gh api repos/{repo}/contents/{cycle_dir} failed "
+                f"(exit {exc.returncode}): {(exc.stderr or '').strip()}"
+            ) from exc
+        except subprocess.TimeoutExpired as exc:
+            raise BaseCycleDocFetchError(
+                f"gh api repos/{repo}/contents/{cycle_dir} timed out after {exc.timeout}s"
+            ) from exc
+
+        dirs_listed.append(cycle_dir)
+        try:
+            entries = json.loads(listing_result.stdout)
+        except json.JSONDecodeError as exc:
+            raise BaseCycleDocFetchError(
+                f"GitHub contents API returned malformed JSON for {cycle_dir} listing."
+            ) from exc
+
+        candidates.extend(
+            entry
+            for entry in entries
+            if isinstance(entry, dict)
+            and entry.get("type") == "file"
+            and isinstance(entry.get("name"), str)
+            and pattern.match(entry["name"])
         )
-    except FileNotFoundError as exc:
-        raise BaseCycleDocFetchError(
-            "gh CLI not on PATH; cannot read cycle docs from base ref."
-        ) from exc
-    except subprocess.CalledProcessError as exc:
-        raise BaseCycleDocFetchError(
-            f"gh api repos/{repo}/contents/docs/roadmap/cycles failed "
-            f"(exit {exc.returncode}): {exc.stderr.strip()}"
-        ) from exc
-    except subprocess.TimeoutExpired as exc:
-        raise BaseCycleDocFetchError(
-            f"gh api repos/{repo}/contents/docs/roadmap/cycles timed out after {exc.timeout}s"
-        ) from exc
 
-    try:
-        entries = json.loads(listing_result.stdout)
-    except json.JSONDecodeError as exc:
-        raise BaseCycleDocFetchError(
-            "GitHub contents API returned malformed JSON for cycle docs listing."
-        ) from exc
+    if not dirs_listed:
+        # EVERY candidate dir 404'd — no cycle docs anywhere on base ref.
+        # Surface the last 404 so consumers see a concrete actionable error
+        # naming what was tried.
+        raise last_404 or BaseCycleDocFetchError(
+            "no candidate cycle-doc directory found on base ref "
+            f"(tried: {', '.join(CYCLE_DOC_DIRS)})"
+        )
 
-    pattern = re.compile(rf"^cycle{re.escape(cycle_id)}(?:-.+)?\.md$")
-    candidates = [
-        entry
-        for entry in entries
-        if isinstance(entry, dict)
-        and entry.get("type") == "file"
-        and isinstance(entry.get("name"), str)
-        and pattern.match(entry["name"])
-    ]
     if not candidates:
+        # At least one dir existed but doesn't hold the cited cycle —
+        # treat as "new cycle, OK to proceed" (the doc lands in this PR).
         return None
 
     chosen = max(candidates, key=lambda entry: len(entry["name"]))
@@ -657,18 +719,22 @@ def _parse_paginated_commit_messages(raw: str) -> str:
 
 
 def _is_cycle_doc_path(path: str) -> bool:
-    """Match ``docs/roadmap/cycles/cycle<id>(-<slug>)?.md``.
+    """Match ``<cycle_dir>/cycle<id>(-<slug>)?.md`` under any layout.
 
-    The classifier counts only files whose basename starts with
-    ``cycle`` followed by an id character. Sibling files like
-    ``docs/roadmap/cycles/README.md`` are index/meta content and do
-    NOT trigger the plan-PR contract.
+    Accepts both legacy ``docs/roadmap/cycles/`` and the newer
+    ``docs/cycles/`` per ``CYCLE_DOC_DIRS``. The classifier counts only
+    files whose basename starts with ``cycle`` followed by an id
+    character. Sibling files like ``<cycle_dir>/README.md`` are
+    index/meta content and do NOT trigger the plan-PR contract.
     """
-    prefix = "docs/roadmap/cycles/cycle"
-    if not path.startswith(prefix) or not path.endswith(".md"):
+    if not path.endswith(".md"):
         return False
-    next_char = path[len(prefix) : len(prefix) + 1]
-    return next_char.isdigit()
+    for cycle_dir in CYCLE_DOC_DIRS:
+        prefix = f"{cycle_dir}/cycle"
+        if path.startswith(prefix):
+            next_char = path[len(prefix) : len(prefix) + 1]
+            return next_char.isdigit()
+    return False
 
 
 def is_plan_pr(
@@ -731,7 +797,9 @@ def status_completion_in_diff(diff: str) -> list[str]:
             in_frontmatter = False
             seen_completed_in_frontmatter = False
             continue
-        if not current_file or not current_file.startswith("docs/roadmap/cycles/"):
+        if not current_file or not any(
+            current_file.startswith(f"{d}/") for d in CYCLE_DOC_DIRS
+        ):
             continue
         # Naive frontmatter tracking inside the diff hunk: ``---`` delimiters
         # toggle the flag. False positives are acceptable here — the goal
@@ -789,7 +857,7 @@ def cycle_docs_transitioned_to_terminal(
     cycle_paths = [
         p
         for p in changed_files
-        if p.startswith("docs/roadmap/cycles/cycle") and p.endswith(".md")
+        if any(p.startswith(f"{d}/cycle") for d in CYCLE_DOC_DIRS) and p.endswith(".md")
     ]
     if not cycle_paths:
         return []
@@ -1030,8 +1098,9 @@ def validate(
         if doc is None:
             errors.append(
                 f"[cycle-doc] FAIL ({pr_type}): cycle `{cycle_id}` not found in "
-                f"`docs/roadmap/cycles/`. Either fix the trailer or open a plan "
-                "PR that creates the cycle doc first."
+                f"any of: {', '.join(f'`{d}/`' for d in CYCLE_DOC_DIRS)}. "
+                "Either fix the trailer or open a plan PR that creates the "
+                "cycle doc first."
             )
             return errors
 
@@ -1056,7 +1125,9 @@ def validate(
         # PR that doesn't touch its cycle's doc is mis-labelled.
         assert doc is not None  # plan PR without cycle_id already returned
         cycle_paths = [
-            f for f in changed_files if f.startswith("docs/roadmap/cycles/")
+            f
+            for f in changed_files
+            if any(f.startswith(f"{d}/") for d in CYCLE_DOC_DIRS)
         ]
         doc_relative = doc.path.relative_to(REPO_ROOT).as_posix()
         if doc_relative not in cycle_paths:

package/dist/doctor.d.ts

@@ -9,6 +9,23 @@ export interface DoctorOptions {
     profileName?: string;
 }
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorCheck[]>;
+export declare const CLOUD_ENV_MARKERS: readonly ["CODESPACES", "REMOTE_CONTAINERS", "CLAUDE_CODE_SANDBOX", "DEVCONTAINER"];
+export type CloudEnvMarker = (typeof CLOUD_ENV_MARKERS)[number];
+export interface CloudEnvDetection {
+    detected: boolean;
+    /**
+     * The subset of `CLOUD_ENV_MARKERS` whose values were truthy in
+     * `process.env` at detection time (each one of "true", "1", "yes",
+     * case-insensitive; presence-only markers like a non-empty
+     * `CODESPACE_NAME` are NOT considered — keep the contract explicit
+     * boolean-ish to avoid false positives from generic env-set state).
+     */
+    markers: CloudEnvMarker[];
+}
+export interface DetectCloudEnvOptions {
+    env?: NodeJS.ProcessEnv;
+}
+export declare function detectCloudEnv(options?: DetectCloudEnvOptions): CloudEnvDetection;
 export type DoctorTriageState = "config_missing" | "auth_pending" | "ok";
 export interface ClassifyDoctorStateOptions {
     config: AgentReviewConfig;

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAK1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAO5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAoJ9E;AAkND,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,cAAc,GACd,IAAI,CAAC;AAET,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;;OAMG;IACH,eAAe,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,kBAAkB,CAiDpB;AA0BD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAwDjE;AAoED,eAAO,MAAM,2BAA2B,QACQ,CAAC;AA8GjD,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6F3E"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAM9D,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACZ,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAK1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAO5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA4L9E;AAuBD,eAAO,MAAM,iBAAiB,qFAKpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,iBAAiB,CAYnB;AAiPD,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,cAAc,GACd,IAAI,CAAC;AAET,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;;;OAMG;IACH,eAAe,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,kBAAkB,CAiDpB;AA0BD,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAwDjE;AAoED,eAAO,MAAM,2BAA2B,QACQ,CAAC;AA8GjD,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6F3E"}