docspec 0.2.0 → 0.4.0

package/dist/changed.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDocspecChangedPrompt = buildDocspecChangedPrompt;
+const fs = __importStar(require("fs/promises"));
+const fsSync = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const path_utils_1 = require("./path-utils");
+const DEFAULT_MAX_DOCSPECS = 10;
+const DEFAULT_MAX_DIFF_CHARS = 120000;
+/**
+ * List changed files via git diff --name-only base...merge
+ */
+function listChangedFiles(base, merge, repoRoot) {
+    const out = (0, child_process_1.execSync)(`git diff --name-only ${base}...${merge}`, {
+        encoding: "utf-8",
+        cwd: repoRoot,
+    }).trim();
+    return out ? out.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+}
+/**
+ * Get diff text via git diff base...merge, truncated if needed.
+ */
+function getDiffText(base, merge, repoRoot, maxChars) {
+    let diff;
+    try {
+        diff = (0, child_process_1.execSync)(`git diff ${base}...${merge}`, { encoding: "utf-8", cwd: repoRoot });
+    }
+    catch {
+        return "";
+    }
+    if (diff.length > maxChars) {
+        diff = diff.slice(0, maxChars) + "\n\n[DIFF TRUNCATED]\n";
+    }
+    return diff;
+}
+/**
+ * Find all docspec paths under .docspec/ in the repo.
+ */
+async function findAllDocspecPaths(docspecDir) {
+    const files = [];
+    try {
+        const entries = await fs.readdir(docspecDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(docspecDir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...(await findAllDocspecPaths(full)));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".docspec.md")) {
+                files.push(full);
+            }
+        }
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    return files;
+}
+/**
+ * Find candidate docspec files to process given changed files.
+ * Strategy:
+ * 1) Changed files that are under .docspec/ and end with .docspec.md are included.
+ * 2) For each other changed file, walk up from its directory to repo root; at each level,
+ *    include docspecs whose target markdown lives in that directory.
+ */
+function findCandidateDocspecs(repoRoot, docspecPaths, changedFiles, maxDocspecs) {
+    const candidates = [];
+    const seen = new Set();
+    const add = (p) => {
+        const norm = path.normalize(p).replace(/\\/g, "/");
+        if (!seen.has(norm)) {
+            seen.add(norm);
+            candidates.push(p);
+        }
+    };
+    // 1) Directly changed docspecs (under .docspec/)
+    for (const f of changedFiles) {
+        const normalized = path.normalize(f).replace(/\\/g, "/");
+        if ((0, path_utils_1.isDocspecPath)(normalized)) {
+            const full = path.join(repoRoot, f);
+            add(full);
+        }
+    }
+    // 2) For each changed file, walk up directory and include docspecs whose target markdown is in that directory
+    for (const f of changedFiles) {
+        const normalized = path.normalize(f).replace(/\\/g, "/");
+        if (normalized.startsWith(".docspec/"))
+            continue; // already handled
+        const fullPath = path.join(repoRoot, f);
+        let dir = path.dirname(fullPath);
+        while (true) {
+            const relDir = path.relative(repoRoot, dir).replace(/\\/g, "/") || ".";
+            for (const { docspecPath, targetMdPath } of docspecPaths) {
+                const targetDir = path.dirname(targetMdPath).replace(/\\/g, "/") || ".";
+                if (targetDir === relDir) {
+                    add(docspecPath);
+                }
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir || path.relative(repoRoot, parent).startsWith(".."))
+                break;
+            dir = parent;
+        }
+        // Include if the changed file is the target markdown
+        for (const { docspecPath, targetMdPath } of docspecPaths) {
+            if (path.normalize(f).replace(/\\/g, "/") === path.normalize(targetMdPath).replace(/\\/g, "/")) {
+                add(docspecPath);
+            }
+        }
+    }
+    return candidates.slice(0, maxDocspecs);
+}
+/**
+ * Build the changed prompt (sync markdown with docspecs from PR changes) and return it.
+ * If options.outputPath is set, writes the prompt to that file.
+ */
+async function buildDocspecChangedPrompt(options) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const docspecDir = path.join(repoRoot, ".docspec");
+    let changedFiles = options.changedFiles ?? [];
+    let diffText = "";
+    if (changedFiles.length === 0 && options.base && options.merge) {
+        changedFiles = listChangedFiles(options.base, options.merge, repoRoot);
+        diffText = getDiffText(options.base, options.merge, repoRoot, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+    }
+    else if (options.changedFiles && options.changedFiles.length > 0 && options.base && options.merge) {
+        diffText = getDiffText(options.base, options.merge, repoRoot, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+    }
+    const allDocspecPaths = await findAllDocspecPaths(docspecDir);
+    const docspecWithTargets = allDocspecPaths
+        .map((p) => {
+        const rel = path.relative(repoRoot, p).replace(/\\/g, "/");
+        const targetMd = (0, path_utils_1.docspecToMarkdownPath)(rel);
+        return { docspecPath: p, targetMdPath: targetMd };
+    })
+        .filter(({ docspecPath }) => fsSync.existsSync(docspecPath));
+    const candidates = findCandidateDocspecs(repoRoot, docspecWithTargets, changedFiles, options.maxDocspecs ?? DEFAULT_MAX_DOCSPECS);
+    const parts = [
+        "Merged PR diff (context):",
+        "<diff>",
+        diffText || "(no diff available)",
+        "</diff>",
+        "",
+        "The following docspec files were discovered based on the PR changes. For each docspec, check if its target markdown file needs to be updated based on the code changes:",
+        "",
+    ];
+    let added = 0;
+    for (const docspecPath of candidates) {
+        const relDocspec = path.relative(repoRoot, docspecPath).replace(/\\/g, "/");
+        const targetMdPath = (0, path_utils_1.docspecToMarkdownPath)(relDocspec);
+        const targetFull = path.join(repoRoot, targetMdPath);
+        try {
+            await fs.access(targetFull);
+        }
+        catch {
+            continue;
+        }
+        const docspecContent = await fs.readFile(docspecPath, "utf-8");
+        const mdContent = await fs.readFile(targetFull, "utf-8");
+        parts.push(`## Docspec: ${relDocspec}`, `Target markdown: ${targetMdPath}`, "", "<docspec>", docspecContent, "</docspec>", "", "<markdown>", mdContent, "</markdown>", "");
+        added++;
+    }
+    if (added === 0) {
+        return { prompt: "", outputPath: null };
+    }
+    parts.push("Task:", "1. Explore the repository using your available tools to understand the codebase context", "2. Understand how the code changes in the diff relate to each docspec's requirements", "3. For each markdown file listed above, check if it already satisfies its docspec given the code changes", "4. Only update markdown files if changes are actually necessary to satisfy their docspecs - avoid making unnecessary changes", "5. Use the Edit tool to modify markdown files directly if changes are needed", "6. Do not provide any text output - files are modified directly using tools");
+    const prompt = parts.join("\n");
+    const outPath = options.outputPath ? path.resolve(repoRoot, options.outputPath) : null;
+    if (outPath && prompt) {
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, prompt, "utf-8");
+    }
+    return { prompt, outputPath: outPath };
+}
+//# sourceMappingURL=changed.js.map

package/dist/changed.js.map

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

package/dist/cli.js

@@ -35,99 +35,116 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
-const validator_1 = require("./validator");
-const generator_1 = require("./generator");
+const create_1 = require("./create");
+const logger_1 = require("./logger");
+const path_utils_1 = require("./path-utils");
+const changed_1 = require("./changed");
+const generate_1 = require("./generate");
 const program = new commander_1.Command();
 program
     .name("docspec")
-    .description("Generate and validate docspec files (*.docspec.md)")
-    .version("0.1.0");
-program
-    .command("validate")
-    .description("Validate docspec files")
-    .argument("[paths...]", "Paths to docspec files (if not provided, finds all *.docspec.md files)")
-    .action(async (filePaths) => {
-    let filesToValidate = [];
-    if (filePaths.length > 0) {
-        // Use provided file paths (from pre-commit or user)
-        filesToValidate = filePaths;
+    .description("Generate docspec files and prompts under .docspec/")
+    .version("0.3.0")
+    .option("-v, --verbose", "Enable verbose output with detailed logging")
+    .argument("[markdown_path]", "Path to markdown file (creates .docspec/<path>.docspec.md)")
+    .action(async (markdownPath) => {
+    if (!markdownPath)
+        return;
+    const opts = program.opts();
+    logger_1.logger.setVerbose(opts.verbose || false);
+    try {
+        const resolved = path.resolve(process.cwd(), markdownPath).replace(/\\/g, "/");
+        const cwd = process.cwd().replace(/\\/g, "/");
+        const relativeMd = resolved.startsWith(cwd)
+            ? path.relative(cwd, resolved).replace(/\\/g, "/")
+            : markdownPath;
+        await (0, create_1.generateDocspec)(relativeMd);
+        logger_1.logger.success(`Generated docspec file: ${(0, path_utils_1.markdownToDocspecPath)(relativeMd)}`);
     }
-    else {
-        // Find all *.docspec.md files in current directory tree
-        filesToValidate = await findDocspecFiles(process.cwd());
+    catch (error) {
+        logger_1.logger.error(`Failed to generate docspec file: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
     }
-    if (filesToValidate.length === 0) {
-        console.log("No docspec files found to validate.");
-        process.exit(0);
+});
+program
+    .command("changed")
+    .description("Generate a prompt to sync markdown files with their docspecs based on changed files (for use with an external LLM)")
+    .option("--changed-files <paths>", "Comma-separated list of changed file paths (or omit and use --base/--merge for git diff)")
+    .option("--base <sha>", "Base SHA for git diff (e.g. PR base)")
+    .option("--merge <sha>", "Merge SHA for git diff (e.g. PR merge commit)")
+    .option("--output <file>", "Write prompt to this file", "prompt.txt")
+    .option("--max-docspecs <n>", "Max docspecs to include", "10")
+    .option("--max-diff-chars <n>", "Max characters of diff to include", "120000")
+    .action(async function () {
+    const opts = program.opts();
+    logger_1.logger.setVerbose(opts.verbose || false);
+    const cmdOpts = this.opts();
+    const changedFiles = cmdOpts.changedFiles
+        ? String(cmdOpts.changedFiles).split(",").map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const base = cmdOpts.base;
+    const merge = cmdOpts.merge;
+    if (!changedFiles?.length && (!base || !merge)) {
+        logger_1.logger.error("Either provide --changed-files or both --base and --merge for git diff.");
+        process.exit(1);
     }
-    let hasErrors = false;
-    for (const filePath of filesToValidate) {
-        const result = await (0, validator_1.validateDocspec)(filePath);
-        if (!result.valid) {
-            hasErrors = true;
-            console.error(`\n❌ ${filePath}:`);
-            for (const error of result.errors) {
-                console.error(`  - ${error}`);
-            }
+    try {
+        const { prompt, outputPath } = await (0, changed_1.buildDocspecChangedPrompt)({
+            changedFiles,
+            base,
+            merge,
+            outputPath: cmdOpts.output || "prompt.txt",
+            maxDocspecs: parseInt(String(cmdOpts.maxDocspecs), 10),
+            maxDiffChars: parseInt(String(cmdOpts.maxDiffChars), 10),
+        });
+        if (!prompt) {
+            logger_1.logger.info("No relevant docspec files found; no prompt written.");
+            process.exit(0);
         }
-        else {
-            console.log(`✅ ${filePath}`);
+        if (outputPath) {
+            logger_1.logger.success(`Prompt written to ${outputPath}`);
+            console.log(outputPath);
         }
     }
-    if (hasErrors) {
+    catch (error) {
+        logger_1.logger.error(error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
 });
 program
     .command("generate")
-    .description("Generate a new docspec file")
-    .argument("<path>", "Path where the docspec file should be created (must end with .docspec.md)")
-    .action(async (filePath) => {
+    .description("Generate a new docspec for a markdown file and output a prompt for an external LLM to fill/improve it")
+    .argument("<markdown_path>", "Path to the markdown file (e.g. README.md, docs/deploy.md)")
+    .option("--overwrite", "Overwrite existing docspec file")
+    .option("--output-prompt <file>", "Write implementation prompt to this file", "prompt.txt")
+    .option("--output-plan <file>", "Write plan prompt to this file (optional)")
+    .action(async function (markdownPath) {
+    const opts = program.opts();
+    logger_1.logger.setVerbose(opts.verbose || false);
+    const cmdOpts = this.opts();
+    const resolvedMd = path.resolve(process.cwd(), markdownPath).replace(/\\/g, "/");
+    const cwd = process.cwd().replace(/\\/g, "/");
+    const relativeMd = resolvedMd.startsWith(cwd)
+        ? path.relative(cwd, resolvedMd).replace(/\\/g, "/")
+        : markdownPath;
     try {
-        // Ensure the path ends with .docspec.md
-        if (!filePath.endsWith(".docspec.md")) {
-            filePath = filePath + ".docspec.md";
+        const result = await (0, generate_1.buildDocspecGeneratePrompts)({
+            markdownPath: relativeMd,
+            overwrite: cmdOpts.overwrite === true,
+            outputPromptPath: cmdOpts.outputPrompt || "prompt.txt",
+            outputPlanPath: cmdOpts.outputPlan,
+        });
+        logger_1.logger.success(`Docspec written to ${(0, path_utils_1.markdownToDocspecPath)(relativeMd)}`);
+        if (result.outputPromptPath) {
+            logger_1.logger.success(`Prompt written to ${result.outputPromptPath}`);
+            console.log(result.outputPromptPath);
         }
-        await (0, generator_1.generateDocspec)(filePath);
-        console.log(`✅ Generated docspec file: ${filePath}`);
     }
     catch (error) {
-        console.error(`❌ Failed to generate docspec file: ${error instanceof Error ? error.message : String(error)}`);
+        logger_1.logger.error(error instanceof Error ? error.message : String(error));
         process.exit(1);
     }
 });
-// Parse command line arguments
 program.parse();
-/**
- * Recursively find all *.docspec.md files in a directory
- */
-async function findDocspecFiles(dir) {
-    const files = [];
-    try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            // Skip node_modules and .git directories
-            if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
-                continue;
-            }
-            if (entry.isDirectory()) {
-                const subFiles = await findDocspecFiles(fullPath);
-                files.push(...subFiles);
-            }
-            else if (entry.isFile() && entry.name.endsWith(".docspec.md")) {
-                files.push(fullPath);
-            }
-        }
-    }
-    catch (error) {
-        // Ignore permission errors
-        if (error instanceof Error && "code" in error && error.code !== "EACCES") {
-            throw error;
-        }
-    }
-    return files;
-}
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/constants.d.ts

@@ -1,9 +1,11 @@
 /**
  * Required section headers for docspec files
+ * Lazily loaded on first access to ensure logger is configured
  */
 export declare const REQUIRED_SECTIONS: readonly string[];
 /**
  * Boilerplate template text for each section
+ * Lazily loaded on first access to ensure logger is configured
  */
 export declare const SECTION_BOILERPLATE: Record<string, string>;
 /**

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAwBA;;GAEG;AACH,eAAO,MAAM,iBAAiB,mBAG1B,CAAC;AAEL;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOnD,CAAC;AAEL;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CA0BjE"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAyDA;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EA8CxB,SAAS,MAAM,EAAE,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwBrD,CAAC;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAmCjE"}

package/dist/constants.js

@@ -2,66 +2,169 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SECTION_BOILERPLATE = exports.REQUIRED_SECTIONS = void 0;
 exports.getDocspecTemplate = getDocspecTemplate;
-const format_parser_1 = require("./format-parser");
+const template_1 = require("./template");
+const logger_1 = require("./logger");
 let cachedFormat = null;
+let cachedRequiredSections = null;
+let cachedSectionBoilerplate = null;
 /**
  * Load and cache the format definition
  */
 function loadFormat() {
     if (cachedFormat) {
+        logger_1.logger.debug("Using cached format definition");
         return cachedFormat;
     }
     try {
-        const formatPath = (0, format_parser_1.getFormatFilePath)();
-        cachedFormat = (0, format_parser_1.parseFormatFile)(formatPath);
+        logger_1.logger.debug("Loading format definition");
+        const formatPath = (0, template_1.getFormatFilePath)();
+        logger_1.logger.debug(`Format file path: ${formatPath}`);
+        cachedFormat = (0, template_1.parseFormatFile)(formatPath);
+        logger_1.logger.debug(`Format loaded: ${cachedFormat.sections.length} section(s) found`);
         return cachedFormat;
     }
     catch (error) {
+        logger_1.logger.debug(`Error loading format: ${error instanceof Error ? error.message : String(error)}`);
         throw new Error(`Failed to load docspec format file: ${error instanceof Error ? error.message : String(error)}\n` +
-            `Make sure docspec-format.md exists in the project root.`);
+            `The template is at .docspec/docspec.md (it is seeded from the default on first run).`);
     }
 }
+/**
+ * Get required sections (lazy-loaded)
+ */
+function getRequiredSections() {
+    if (cachedRequiredSections === null) {
+        const format = loadFormat();
+        cachedRequiredSections = format.sections.map(s => s.name);
+    }
+    return cachedRequiredSections;
+}
+/**
+ * Get section boilerplate (lazy-loaded)
+ */
+function getSectionBoilerplate() {
+    if (cachedSectionBoilerplate === null) {
+        const format = loadFormat();
+        cachedSectionBoilerplate = {};
+        for (const section of format.sections) {
+            cachedSectionBoilerplate[section.name] = section.boilerplate;
+        }
+    }
+    return cachedSectionBoilerplate;
+}
 /**
  * Required section headers for docspec files
+ * Lazily loaded on first access to ensure logger is configured
  */
-exports.REQUIRED_SECTIONS = (() => {
-    const format = loadFormat();
-    return format.sections.map(s => s.name);
-})();
+exports.REQUIRED_SECTIONS = new Proxy([], {
+    get(target, prop) {
+        const sections = getRequiredSections();
+        if (typeof prop === 'string') {
+            const index = parseInt(prop, 10);
+            if (!isNaN(index)) {
+                return sections[index];
+            }
+            if (prop === 'length') {
+                return sections.length;
+            }
+            if (prop === 'forEach' || prop === 'map' || prop === 'filter' || prop === 'includes' || prop === 'indexOf' || prop === 'slice' || prop === 'join') {
+                return sections[prop].bind(sections);
+            }
+        }
+        return sections[prop];
+    },
+    ownKeys() {
+        return Object.keys(getRequiredSections());
+    },
+    getOwnPropertyDescriptor(target, prop) {
+        const sections = getRequiredSections();
+        if (typeof prop === 'string') {
+            const index = parseInt(prop, 10);
+            if (!isNaN(index) && index >= 0 && index < sections.length) {
+                return { enumerable: true, configurable: true, value: sections[index] };
+            }
+            if (prop === 'length') {
+                return { enumerable: false, configurable: false, value: sections.length };
+            }
+        }
+        return undefined;
+    },
+    has(target, prop) {
+        const sections = getRequiredSections();
+        if (typeof prop === 'string') {
+            const index = parseInt(prop, 10);
+            if (!isNaN(index) && index >= 0 && index < sections.length) {
+                return true;
+            }
+            if (prop === 'length') {
+                return true;
+            }
+        }
+        return prop in sections;
+    }
+});
 /**
  * Boilerplate template text for each section
+ * Lazily loaded on first access to ensure logger is configured
  */
-exports.SECTION_BOILERPLATE = (() => {
-    const format = loadFormat();
-    const boilerplate = {};
-    for (const section of format.sections) {
-        boilerplate[section.name] = section.boilerplate;
+exports.SECTION_BOILERPLATE = new Proxy({}, {
+    get(target, prop) {
+        const boilerplate = getSectionBoilerplate();
+        return boilerplate[prop];
+    },
+    set(target, prop, value) {
+        const boilerplate = getSectionBoilerplate();
+        boilerplate[prop] = value;
+        return true;
+    },
+    ownKeys() {
+        return Object.keys(getSectionBoilerplate());
+    },
+    getOwnPropertyDescriptor(target, prop) {
+        const boilerplate = getSectionBoilerplate();
+        if (prop in boilerplate) {
+            return { enumerable: true, configurable: true, value: boilerplate[prop] };
+        }
+        return undefined;
+    },
+    has(target, prop) {
+        const boilerplate = getSectionBoilerplate();
+        return prop in boilerplate;
     }
-    return boilerplate;
-})();
+});
 /**
  * Generate the full docspec template
  * @param targetFilePath The path to the target markdown file (e.g., "README.md")
  */
 function getDocspecTemplate(targetFilePath) {
+    logger_1.logger.debug(`Generating template for target file: ${targetFilePath}`);
     const format = loadFormat();
     // Replace {{TARGET_FILE}} in template
     let template = format.template.replace(/\{\{TARGET_FILE\}\}/g, targetFilePath);
+    logger_1.logger.debug("Replaced {{TARGET_FILE}} placeholder in template");
     // Handle agent instructions if present
     let agentInstructionsSection = "";
     if (format.agentInstructions) {
+        logger_1.logger.debug("Agent instructions found, including in template");
         // Replace {{TARGET_FILE}} in agent instructions
         const agentContent = format.agentInstructions.replace(/\{\{TARGET_FILE\}\}/g, targetFilePath);
         agentInstructionsSection = `## AGENT INSTRUCTIONS\n\n${agentContent}\n\n`;
     }
+    else {
+        logger_1.logger.debug("No agent instructions found");
+    }
     // Replace {{AGENT_INSTRUCTIONS}} placeholder
     template = template.replace(/\{\{AGENT_INSTRUCTIONS\}\}/g, agentInstructionsSection);
+    logger_1.logger.debug("Replaced {{AGENT_INSTRUCTIONS}} placeholder");
     // Generate sections
+    logger_1.logger.debug(`Generating ${format.sections.length} section(s)`);
     const sections = format.sections.map((section) => {
         return `## ${section.number}. ${section.name}\n\n${section.boilerplate}`;
     }).join("\n\n");
     // Replace {{SECTIONS}} placeholder
     template = template.replace(/\{\{SECTIONS\}\}/g, sections);
+    logger_1.logger.debug("Replaced {{SECTIONS}} placeholder");
+    logger_1.logger.debug(`Template generation complete: ${template.length} characters`);
     return template;
 }
 //# sourceMappingURL=constants.js.map