@edcalderon/versioning 1.0.11 → 1.1.2

package/dist/extensions/reentry-status-extension.js

@@ -0,0 +1,528 @@
+"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 });
+const commander_1 = require("commander");
+const fs = __importStar(require("fs-extra"));
+const path = __importStar(require("path"));
+const config_manager_1 = require("./reentry-status/config-manager");
+const constants_1 = require("./reentry-status/constants");
+const file_manager_1 = require("./reentry-status/file-manager");
+const dirty_detection_1 = require("./reentry-status/dirty-detection");
+const github_rest_client_1 = require("./reentry-status/github-rest-client");
+const github_sync_adapter_1 = require("./reentry-status/github-sync-adapter");
+const obsidian_cli_client_1 = require("./reentry-status/obsidian-cli-client");
+const obsidian_sync_adapter_1 = require("./reentry-status/obsidian-sync-adapter");
+const roadmap_parser_1 = require("./reentry-status/roadmap-parser");
+const roadmap_renderer_1 = require("./reentry-status/roadmap-renderer");
+const status_renderer_1 = require("./reentry-status/status-renderer");
+const reentry_status_manager_1 = require("./reentry-status/reentry-status-manager");
+const extension = {
+    name: constants_1.REENTRY_EXTENSION_NAME,
+    description: 'Maintains canonical re-entry status and synchronizes to files, GitHub Issues, and Obsidian notes',
+    version: '1.1.2',
+    hooks: {
+        postVersion: async (type, version, options) => {
+            try {
+                // Extensions are loaded before the CLI reads config per-command; use global config snapshot.
+                const configPath = options?.config ?? 'versioning.config.json';
+                if (!(await fs.pathExists(configPath)))
+                    return;
+                const cfg = await fs.readJson(configPath);
+                const reentryCfg = config_manager_1.ConfigManager.loadConfig(cfg);
+                if (!reentryCfg.enabled || !reentryCfg.autoSync)
+                    return;
+                if (reentryCfg.hooks?.postVersion === false)
+                    return;
+                const manager = new reentry_status_manager_1.ReentryStatusManager({ fileManager: new file_manager_1.FileManager() });
+                await manager.applyContext(cfg, {
+                    trigger: 'postVersion',
+                    command: 'versioning bump',
+                    options,
+                    gitInfo: { branch: '', commit: '', author: '', timestamp: new Date().toISOString() },
+                    versioningInfo: { versionType: type, oldVersion: undefined, newVersion: version }
+                });
+                await manager.syncAll(cfg);
+            }
+            catch (error) {
+                console.warn('⚠️  reentry-status postVersion hook failed:', error instanceof Error ? error.message : String(error));
+            }
+        },
+        postRelease: async (version, options) => {
+            try {
+                const configPath = options?.config ?? 'versioning.config.json';
+                if (!(await fs.pathExists(configPath)))
+                    return;
+                const cfg = await fs.readJson(configPath);
+                const reentryCfg = config_manager_1.ConfigManager.loadConfig(cfg);
+                if (!reentryCfg.enabled || !reentryCfg.autoSync)
+                    return;
+                if (reentryCfg.hooks?.postRelease !== true)
+                    return;
+                const manager = new reentry_status_manager_1.ReentryStatusManager({ fileManager: new file_manager_1.FileManager() });
+                await manager.applyContext(cfg, {
+                    trigger: 'postRelease',
+                    command: 'versioning release',
+                    options,
+                    gitInfo: { branch: '', commit: '', author: '', timestamp: new Date().toISOString() },
+                    versioningInfo: { newVersion: version }
+                });
+                await manager.syncAll(cfg);
+            }
+            catch (error) {
+                console.warn('⚠️  reentry-status postRelease hook failed:', error instanceof Error ? error.message : String(error));
+            }
+        }
+    },
+    register: async (program, rootConfig) => {
+        const fileManager = new file_manager_1.FileManager();
+        const manager = new reentry_status_manager_1.ReentryStatusManager({ fileManager });
+        const discoverWorkspaceProjects = async (configPath) => {
+            const rootDir = path.dirname(configPath);
+            const slugs = new Set();
+            const names = new Set();
+            const considerPackageJson = async (packageJsonPath) => {
+                try {
+                    if (!(await fs.pathExists(packageJsonPath)))
+                        return;
+                    const pkg = await fs.readJson(packageJsonPath);
+                    const name = typeof pkg?.name === 'string' ? String(pkg.name).trim() : '';
+                    if (!name)
+                        return;
+                    names.add(name);
+                    const slug = name.includes('/') ? name.split('/').pop() : name;
+                    if (slug)
+                        slugs.add(String(slug));
+                }
+                catch {
+                    // ignore
+                }
+            };
+            const scanOneLevel = async (baseDir) => {
+                const abs = path.join(rootDir, baseDir);
+                if (!(await fs.pathExists(abs)))
+                    return;
+                const entries = await fs.readdir(abs, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const dirName = entry.name;
+                    if (dirName === 'node_modules' || dirName === 'dist' || dirName === '.git' || dirName === 'archive')
+                        continue;
+                    slugs.add(dirName);
+                    await considerPackageJson(path.join(abs, dirName, 'package.json'));
+                }
+            };
+            const scanTwoLevelsUnderApps = async () => {
+                const absApps = path.join(rootDir, 'apps');
+                if (!(await fs.pathExists(absApps)))
+                    return;
+                const entries = await fs.readdir(absApps, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (!entry.isDirectory())
+                        continue;
+                    const groupDir = path.join(absApps, entry.name);
+                    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git' || entry.name === 'archive')
+                        continue;
+                    const nested = await fs.readdir(groupDir, { withFileTypes: true });
+                    for (const n of nested) {
+                        if (!n.isDirectory())
+                            continue;
+                        if (n.name === 'node_modules' || n.name === 'dist' || n.name === '.git' || n.name === 'archive')
+                            continue;
+                        slugs.add(n.name);
+                        await considerPackageJson(path.join(groupDir, n.name, 'package.json'));
+                    }
+                }
+            };
+            await scanOneLevel('apps');
+            await scanTwoLevelsUnderApps();
+            await scanOneLevel('packages');
+            return { slugs, names };
+        };
+        const validateProjectOption = async (configPath, project) => {
+            const canonical = (0, config_manager_1.canonicalProjectKey)(project);
+            if (!canonical)
+                return undefined;
+            const { slugs, names } = await discoverWorkspaceProjects(configPath);
+            const raw = String(project ?? '').trim();
+            const ok = slugs.has(canonical) || names.has(raw) || names.has(`@ed/${canonical}`) || names.has(`@edcalderon/${canonical}`);
+            if (!ok) {
+                const available = Array.from(slugs).sort().slice(0, 40);
+                const suffix = slugs.size > 40 ? '…' : '';
+                throw new Error(`Unknown project scope: '${raw}'. Expected an existing workspace app/package (try one of: ${available.join(', ')}${suffix}).`);
+            }
+            return canonical;
+        };
+        const loadRootConfigFile = async (configPath) => {
+            if (!(await fs.pathExists(configPath))) {
+                throw new Error(`Config file not found: ${configPath}. Run 'versioning init' to create one.`);
+            }
+            return await fs.readJson(configPath);
+        };
+        const ensureReentryInitialized = async (configPath, migrate, project) => {
+            const validatedProject = await validateProjectOption(configPath, project);
+            const rawCfg = await loadRootConfigFile(configPath);
+            const resolved = config_manager_1.ConfigManager.loadConfig(rawCfg, validatedProject);
+            const cfg = {
+                ...rawCfg,
+                reentryStatus: {
+                    ...(rawCfg.reentryStatus ?? {}),
+                    files: resolved.files,
+                },
+            };
+            const reentryCfg = config_manager_1.ConfigManager.loadConfig(cfg, validatedProject);
+            await fs.ensureDir(path.dirname(reentryCfg.files.jsonPath));
+            const defaultRoadmapPath = path.join(path.dirname(reentryCfg.files.jsonPath), constants_1.ROADMAP_MD_FILENAME);
+            const existingJson = await fileManager.readFileIfExists(reentryCfg.files.jsonPath);
+            if (existingJson) {
+                const parsed = status_renderer_1.StatusRenderer.parseJson(existingJson);
+                if (migrate && parsed.schemaVersion === '1.0') {
+                    // Explicit migration: rewrite as 1.1 without changing semantics.
+                    const migrated = {
+                        ...parsed,
+                        schemaVersion: '1.1',
+                        milestone: parsed.milestone ?? null,
+                        roadmapFile: defaultRoadmapPath
+                    };
+                    await fileManager.writeStatusJson(cfg, migrated);
+                    return { cfg, status: migrated };
+                }
+                const normalized = {
+                    ...parsed,
+                    schemaVersion: '1.1',
+                    roadmapFile: parsed.roadmapFile || defaultRoadmapPath,
+                };
+                return { cfg, status: normalized };
+            }
+            const initial = {
+                schemaVersion: '1.1',
+                version: '0.0.0',
+                lastUpdated: new Date(0).toISOString(),
+                updatedBy: 'unknown',
+                context: {
+                    trigger: 'manual',
+                    gitInfo: { branch: '', commit: '', author: '', timestamp: new Date(0).toISOString() },
+                    versioningInfo: {}
+                },
+                milestone: null,
+                roadmapFile: defaultRoadmapPath,
+                currentPhase: 'planning',
+                milestones: [],
+                blockers: [],
+                nextSteps: [],
+                risks: [],
+                dependencies: [],
+                versioning: {
+                    currentVersion: '0.0.0',
+                    previousVersion: '0.0.0',
+                    versionType: 'patch'
+                },
+                syncMetadata: {
+                    lastSyncAttempt: new Date(0).toISOString(),
+                    lastSuccessfulSync: new Date(0).toISOString()
+                }
+            };
+            await fileManager.writeStatusFiles(cfg, initial);
+            return { cfg, status: initial };
+        };
+        program
+            .command('reentry')
+            .description('Manage re-entry status (fast layer)')
+            .addCommand(new commander_1.Command('init')
+            .description('Initialize re-entry status files')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .option('--migrate', 'rewrite v1.0 schema to v1.1 (no semantic changes)', false)
+            .action(async (options) => {
+            const { status } = await ensureReentryInitialized(options.config, Boolean(options.migrate), options.project);
+            console.log(`✅ Initialized re-entry status (schema ${status.schemaVersion})`);
+        }))
+            .addCommand(new commander_1.Command('set')
+            .description('Update re-entry status fields (fast layer)')
+            .option('--phase <phase>', 'Set current phase')
+            .option('--next <text>', 'Set next micro-step (replaces first nextSteps entry)')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .option('--migrate', 'rewrite v1.0 schema to v1.1 (no semantic changes)', false)
+            .action(async (options) => {
+            const { cfg, status } = await ensureReentryInitialized(options.config, Boolean(options.migrate), options.project);
+            const nextStepText = typeof options.next === 'string' ? options.next.trim() : '';
+            const phase = typeof options.phase === 'string' ? options.phase.trim() : '';
+            const updated = {
+                ...status,
+                schemaVersion: '1.1',
+                currentPhase: phase ? phase : status.currentPhase,
+                nextSteps: nextStepText
+                    ? [{ id: 'next', description: nextStepText, priority: 1 }]
+                    : status.nextSteps,
+                lastUpdated: new Date().toISOString()
+            };
+            await manager.updateStatus(cfg, () => updated);
+            console.log('✅ Re-entry status updated');
+        }))
+            .addCommand(new commander_1.Command('sync')
+            .description('Ensure generated status files exist and are up to date (idempotent)')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .option('--migrate', 'rewrite v1.0 schema to v1.1 (no semantic changes)', false)
+            .action(async (options) => {
+            const { cfg, status } = await ensureReentryInitialized(options.config, Boolean(options.migrate), options.project);
+            const reentryCfg = config_manager_1.ConfigManager.loadConfig(cfg, options.project);
+            // Ensure ROADMAP exists (light touch: only managed block is updated).
+            const roadmapPath = status.roadmapFile || roadmap_renderer_1.RoadmapRenderer.defaultRoadmapPath();
+            const existing = await fileManager.readFileIfExists(roadmapPath);
+            if (!existing) {
+                await fileManager.writeFileIfChanged(roadmapPath, roadmap_renderer_1.RoadmapRenderer.renderTemplate({}, { milestone: status.milestone, roadmapFile: roadmapPath }));
+            }
+            else {
+                const upserted = roadmap_renderer_1.RoadmapRenderer.upsertManagedBlock(existing, { milestone: status.milestone, roadmapFile: roadmapPath });
+                if (upserted.changed) {
+                    await fileManager.writeFileIfChanged(roadmapPath, upserted.content);
+                }
+            }
+            // Always ensure JSON + REENTRY.md are consistent.
+            await fileManager.writeStatusFiles(cfg, status);
+            const reentryMarkdown = status_renderer_1.StatusRenderer.renderMarkdown(status);
+            // Optional external sync targets (fail-soft by default).
+            let nextStatus = status;
+            if (reentryCfg.github?.enabled) {
+                try {
+                    const client = new github_rest_client_1.GitHubRestClient(reentryCfg.github.auth.token);
+                    const adapter = new github_sync_adapter_1.GitHubSyncAdapter(reentryCfg.github, client);
+                    const result = await adapter.sync(nextStatus, reentryMarkdown);
+                    const body = adapter.renderIssueBody(nextStatus, reentryMarkdown);
+                    const bodyHash = (0, dirty_detection_1.sha256)(body);
+                    if (result.details?.created || result.details?.updated) {
+                        nextStatus = {
+                            ...nextStatus,
+                            schemaVersion: '1.1',
+                            syncMetadata: {
+                                ...nextStatus.syncMetadata,
+                                githubIssueId: result.details.issueId ?? nextStatus.syncMetadata.githubIssueId,
+                                githubIssueUrl: result.details.url ?? nextStatus.syncMetadata.githubIssueUrl,
+                                published: {
+                                    ...(nextStatus.syncMetadata.published ?? {}),
+                                    githubIssueBodySha256: bodyHash
+                                }
+                            }
+                        };
+                        await fileManager.writeStatusFiles(cfg, nextStatus);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (reentryCfg.failHard)
+                        throw error;
+                    console.warn(`⚠️  GitHub sync skipped: ${message}`);
+                }
+            }
+            if (reentryCfg.obsidian?.enabled) {
+                try {
+                    const available = await obsidian_cli_client_1.ObsidianCliClient.isAvailable();
+                    if (!available) {
+                        throw new Error('obsidian CLI not available (enable it in Obsidian Settings → General → Command line interface)');
+                    }
+                    const client = new obsidian_cli_client_1.ObsidianCliClient();
+                    const adapter = new obsidian_sync_adapter_1.ObsidianSyncAdapter(reentryCfg.obsidian, client);
+                    const result = await adapter.sync(nextStatus, reentryMarkdown);
+                    const content = adapter.renderNoteContent(nextStatus, reentryMarkdown);
+                    const contentHash = (0, dirty_detection_1.sha256)(content);
+                    if (result.details?.updated) {
+                        nextStatus = {
+                            ...nextStatus,
+                            schemaVersion: '1.1',
+                            syncMetadata: {
+                                ...nextStatus.syncMetadata,
+                                obsidianNotePath: reentryCfg.obsidian.notePath,
+                                published: {
+                                    ...(nextStatus.syncMetadata.published ?? {}),
+                                    obsidianNoteBodySha256: contentHash
+                                }
+                            }
+                        };
+                        await fileManager.writeStatusFiles(cfg, nextStatus);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (reentryCfg.failHard)
+                        throw error;
+                    console.warn(`⚠️  Obsidian sync skipped: ${message}`);
+                }
+            }
+            console.log('✅ Re-entry sync complete');
+        }));
+        program
+            .command('roadmap')
+            .description('Manage roadmap/backlog (slow layer)')
+            .addCommand(new commander_1.Command('init')
+            .description(`Create ${constants_1.REENTRY_STATUS_DIRNAME}/${constants_1.ROADMAP_MD_FILENAME} if missing and ensure managed header block`)
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .option('-t, --title <title>', 'project title for ROADMAP.md template', 'Untitled')
+            .action(async (options) => {
+            const projectKey = await validateProjectOption(options.config, options.project);
+            const { cfg, status } = await ensureReentryInitialized(options.config, false, projectKey);
+            const roadmapPath = status.roadmapFile || roadmap_renderer_1.RoadmapRenderer.defaultRoadmapPath();
+            // If a project is specified and title is left default, prefer a non-stale title.
+            const title = projectKey && String(options.title).trim() === 'Untitled'
+                ? String(options.project ?? projectKey)
+                : String(options.title);
+            const existing = await fileManager.readFileIfExists(roadmapPath);
+            if (!existing) {
+                await fileManager.writeFileIfChanged(roadmapPath, roadmap_renderer_1.RoadmapRenderer.renderTemplate({ projectTitle: title }, { milestone: status.milestone, roadmapFile: roadmapPath }));
+                console.log(`✅ Created ${roadmapPath}`);
+                return;
+            }
+            const upserted = roadmap_renderer_1.RoadmapRenderer.upsertManagedBlock(existing, { milestone: status.milestone, roadmapFile: roadmapPath });
+            if (upserted.changed) {
+                await fileManager.writeFileIfChanged(roadmapPath, upserted.content);
+                console.log(`✅ Updated managed block in ${roadmapPath}`);
+            }
+            else {
+                console.log(`✅ ${roadmapPath} already initialized`);
+            }
+            // Keep REENTRY.md consistent with roadmap references.
+            await fileManager.writeReentryMarkdown(cfg, status);
+        }))
+            .addCommand(new commander_1.Command('validate')
+            .description('Validate that project roadmaps correspond to existing workspaces (detect stale roadmaps)')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .action(async (options) => {
+            const { slugs } = await discoverWorkspaceProjects(String(options.config));
+            const projectsDir = path.join(path.dirname(String(options.config)), constants_1.REENTRY_STATUS_DIRNAME, 'projects');
+            if (!(await fs.pathExists(projectsDir))) {
+                console.log('✅ No project roadmaps found');
+                return;
+            }
+            const entries = await fs.readdir(projectsDir, { withFileTypes: true });
+            const stale = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const key = entry.name;
+                if (!slugs.has(key)) {
+                    stale.push(key);
+                }
+            }
+            if (stale.length === 0) {
+                console.log('✅ All project roadmaps match a workspace');
+                return;
+            }
+            console.warn(`⚠️  Stale project roadmaps found (no matching workspace): ${stale.join(', ')}`);
+            process.exitCode = 1;
+        }))
+            .addCommand(new commander_1.Command('list')
+            .description('List roadmap milestones parsed from ROADMAP.md')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .action(async (options) => {
+            const { status } = await ensureReentryInitialized(options.config, false, options.project);
+            const roadmapPath = status.roadmapFile || roadmap_renderer_1.RoadmapRenderer.defaultRoadmapPath();
+            const content = await fileManager.readFileIfExists(roadmapPath);
+            if (!content) {
+                console.warn(`⚠️  ${roadmapPath} not found. Run 'versioning roadmap init' first.`);
+                return;
+            }
+            const parsed = (0, roadmap_parser_1.parseRoadmapMilestones)(content);
+            for (const w of parsed.warnings)
+                console.warn(`⚠️  ${w}`);
+            if (parsed.items.length === 0) {
+                console.log('— No milestones found');
+                return;
+            }
+            for (const item of parsed.items) {
+                const section = item.section ? ` [${item.section}]` : '';
+                console.log(`- ${item.id}: ${item.title}${section}`);
+            }
+        }))
+            .addCommand(new commander_1.Command('set-milestone')
+            .description('Set active milestone link in reentry.status.json')
+            .requiredOption('--id <id>', 'Milestone id (must match a [id] in ROADMAP.md)')
+            .requiredOption('--title <title>', 'Milestone title')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .action(async (options) => {
+            const { cfg, status } = await ensureReentryInitialized(options.config, false, options.project);
+            const next = {
+                ...status,
+                schemaVersion: '1.1',
+                milestone: { id: String(options.id), title: String(options.title) },
+                roadmapFile: status.roadmapFile || roadmap_renderer_1.RoadmapRenderer.defaultRoadmapPath()
+            };
+            await fileManager.writeStatusJson(cfg, next);
+            await fileManager.writeReentryMarkdown(cfg, next);
+            console.log(`✅ Active milestone set to ${String(options.title)} (${String(options.id)})`);
+        }))
+            .addCommand(new commander_1.Command('add')
+            .description('Add a milestone item to ROADMAP.md under a section')
+            .requiredOption('--section <section>', 'Now|Next|Later')
+            .requiredOption('--item <item>', 'Item text')
+            .option('--id <id>', 'Optional explicit id (e.g., now-02)')
+            .option('-c, --config <file>', 'config file path', 'versioning.config.json')
+            .option('-p, --project <name>', 'project scope (separate ROADMAP/REENTRY/status per project)')
+            .action(async (options) => {
+            const { status } = await ensureReentryInitialized(options.config, false, options.project);
+            const roadmapPath = status.roadmapFile || roadmap_renderer_1.RoadmapRenderer.defaultRoadmapPath();
+            const content = await fileManager.readFileIfExists(roadmapPath);
+            if (!content) {
+                console.warn(`⚠️  ${roadmapPath} not found. Run 'versioning roadmap init' first.`);
+                return;
+            }
+            const normalized = content.replace(/\r\n/g, '\n');
+            const lines = normalized.split('\n');
+            const sectionName = String(options.section).trim();
+            const header = `## ${sectionName}`;
+            const headerIndex = lines.findIndex((l) => l.trim() === header);
+            if (headerIndex === -1) {
+                console.warn(`⚠️  Section not found: ${header}.`);
+                return;
+            }
+            const bulletId = options.id ? String(options.id).trim() : undefined;
+            const itemText = String(options.item).trim();
+            const bullet = bulletId ? `- [${bulletId}] ${itemText}` : `- ${itemText}`;
+            // Insert after the header and the following blank line (if any).
+            let insertAt = headerIndex + 1;
+            if (lines[insertAt] === '')
+                insertAt += 1;
+            lines.splice(insertAt, 0, bullet);
+            const next = `${lines.join('\n')}\n`;
+            await fileManager.writeFileIfChanged(roadmapPath, next);
+            console.log(`✅ Added item under ${header}`);
+        }));
+    }
+};
+exports.default = extension;
+//# sourceMappingURL=reentry-status-extension.js.map

package/examples/reentry-status/README.md

@@ -0,0 +1,18 @@
+# Re-entry Status + Roadmap examples
+
+Files in this folder are copy/paste starting points.
+
+- `versioning.config.reentryStatus.example.json`: example config with reentryStatus + roadmap + (optional) GitHub/Obsidian.
+- `reentry.status.v1.1.example.json`: example canonical status (JSON).
+- `REENTRY.md.example`: example generated REENTRY markdown.
+- `ROADMAP.md.example`: example roadmap/backlog template with managed block markers.
+
+Quick start:
+
+```bash
+# In your repo root:
+cp packages/versioning/examples/reentry-status/versioning.config.reentryStatus.example.json versioning.config.json
+versioning reentry init
+versioning roadmap init --title "My Project"
+versioning roadmap list
+```

package/examples/reentry-status/REENTRY.md.example

@@ -0,0 +1,14 @@
+# Re-entry Status
+
+Schema: 1.1
+Version: 0.1.0
+Phase: development
+
+Next micro-step: Run sync + verify ROADMAP managed block
+
+Milestone: Ship stable integration (id: now-01)
+Roadmap: .versioning/ROADMAP.md
+
+## Notes
+
+- This file is generated for stable diffs. Edit ROADMAP.md for long-term planning.

package/examples/reentry-status/ROADMAP.md.example

@@ -0,0 +1,25 @@
+# Project Roadmap – Untitled
+
+<!-- roadmap:managed:start -->
+> Managed by `@edcalderon/versioning` reentry-status-extension.
+> Canonical roadmap file: .versioning/ROADMAP.md
+> Active milestone: Ship stable integration (id: now-01)
+> 
+> Everything outside this block is user-editable.
+<!-- roadmap:managed:end -->
+
+## North Star
+
+- Describe the long-term outcome this project is aiming for.
+
+## Now (1–2 weeks)
+
+- [now-01] Ship stable integration
+
+## Next (4–8 weeks)
+
+- [next-01] Improve reliability
+
+## Later
+
+- [later-01] Optional refactor

package/examples/reentry-status/reentry.status.v1.1.example.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "1.1",
+  "version": "0.1.0",
+  "lastUpdated": "2026-02-11T00:00:00.000Z",
+  "updatedBy": "dev",
+  "context": {
+    "trigger": "manual",
+    "gitInfo": {
+      "branch": "main",
+      "commit": "abc123",
+      "author": "dev",
+      "timestamp": "2026-02-11T00:00:00.000Z"
+    },
+    "versioningInfo": {}
+  },
+  "milestone": {
+    "id": "now-01",
+    "title": "Ship stable integration"
+  },
+  "roadmapFile": ".versioning/ROADMAP.md",
+  "currentPhase": "development",
+  "milestones": [],
+  "blockers": [],
+  "nextSteps": [
+    {
+      "id": "next",
+      "description": "Run sync + verify ROADMAP managed block",
+      "priority": 1
+    }
+  ],
+  "risks": [],
+  "dependencies": [],
+  "versioning": {
+    "currentVersion": "0.1.0",
+    "previousVersion": "0.0.9",
+    "versionType": "patch"
+  },
+  "syncMetadata": {
+    "lastSyncAttempt": "2026-02-11T00:00:00.000Z",
+    "lastSuccessfulSync": "2026-02-11T00:00:00.000Z"
+  }
+}