@shrkcrft/inspector 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/plugin-lifecycle.js

@@ -1,477 +0,0 @@
-/**
- * Plan-only plugin lifecycle helpers driven by a resolved profile.
- *
- * Lifecycle helpers never write source directly. They emit a structured plan
- * containing:
- *   - replaceOps:    safe `replace` plan operations against the profile's
- *                    key-table file, barrels, and other registry files.
- *   - manualSteps:   things the planned-operation model cannot do today
- *                    (rename a folder, delete a folder) when folder ops are
- *                    not requested or not safe.
- *   - conflicts:     anchors that could not be found — surfaced as advisory
- *                    hints (no failure).
- *   - destructive:   `true` for remove; `true` for rename when files need to
- *                    be renamed on disk.
- *
- * The engine has no project-specific knowledge: every path / key style / barrel
- * comes from the supplied `IPluginLifecycleProfile`. A pack contributes the
- * profile via `pluginLifecycleProfileFiles` on the manifest.
- */
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { checkFolderOpSafety } from '@shrkcrft/generator';
-import { join } from 'node:path';
-import { CaseStyle, } from '@shrkcrft/plugin-api';
-export var PluginLifecycleAction;
-(function (PluginLifecycleAction) {
-    PluginLifecycleAction["Rename"] = "rename";
-    PluginLifecycleAction["Remove"] = "remove";
-})(PluginLifecycleAction || (PluginLifecycleAction = {}));
-function readFileSafe(absPath) {
-    if (!existsSync(absPath))
-        return null;
-    try {
-        return readFileSync(absPath, 'utf8');
-    }
-    catch {
-        return null;
-    }
-}
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * Build a global regex that matches `${segment}/${name}` only when
- * `name` ends at a true token boundary (the next character is NOT an
- * identifier-continuation: kebab `-`, underscore `_`, digit, letter, or
- * dot). Prevents `data` from matching inside `dataflow`, `data-flow`, or
- * `data.foo`.
- */
-function segmentBoundaryRegex(segment, name) {
-    return new RegExp(`${escapeRegex(segment)}/${escapeRegex(name)}(?![A-Za-z0-9_\\-.])`, 'g');
-}
-function splitWords(input) {
-    if (!input)
-        return [];
-    // kebab / snake split
-    if (input.includes('-') || input.includes('_')) {
-        return input.split(/[-_]/).filter(Boolean);
-    }
-    // camel / pascal split on case boundaries
-    return input.split(/(?=[A-Z])/).map((w) => w.toLowerCase()).filter(Boolean);
-}
-function toCase(input, style) {
-    const words = splitWords(input);
-    if (words.length === 0)
-        return input;
-    switch (style) {
-        case CaseStyle.Kebab:
-            return words.map((w) => w.toLowerCase()).join('-');
-        case CaseStyle.UpperSnake:
-            return words.map((w) => w.toUpperCase()).join('_');
-        case CaseStyle.Pascal:
-            return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join('');
-        case CaseStyle.Camel: {
-            return words
-                .map((w, i) => i === 0
-                ? w.toLowerCase()
-                : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-                .join('');
-        }
-        default:
-            return input;
-    }
-}
-function pluginKeysEntryRegex(keyTable, name) {
-    const key = toCase(name, keyTable.keyCase);
-    const value = toCase(name, keyTable.valueCase);
-    return new RegExp(`\\s*${escapeRegex(key)}:\\s*['"]${escapeRegex(value)}['"],?\\n`);
-}
-function findFirstMatch(content, re) {
-    if (!content)
-        return null;
-    const m = content.match(re);
-    return m ? m[0] : null;
-}
-function loadProfileContext(projectRoot, profile) {
-    const keyTablePath = profile.keyTable?.path ? join(projectRoot, profile.keyTable.path) : null;
-    const keyTableContent = keyTablePath ? readFileSafe(keyTablePath) : null;
-    const barrels = (profile.barrels ?? []).map((b) => {
-        const absPath = join(projectRoot, b.path);
-        return { barrel: b, absPath, content: readFileSafe(absPath) };
-    });
-    return { projectRoot, keyTablePath, keyTableContent, barrels };
-}
-export function buildPluginRenamePlan(input) {
-    const { projectRoot, profile, oldName, newName } = input;
-    const ctx = loadProfileContext(projectRoot, profile);
-    const replaceOps = [];
-    const manualSteps = [];
-    const conflicts = [];
-    // Key-table entry rename
-    if (profile.keyTable && ctx.keyTableContent) {
-        const keyTablePath = profile.keyTable.path;
-        const keysFind = findFirstMatch(ctx.keyTableContent, pluginKeysEntryRegex(profile.keyTable, oldName));
-        if (keysFind) {
-            const oldKey = toCase(oldName, profile.keyTable.keyCase);
-            const newKey = toCase(newName, profile.keyTable.keyCase);
-            const oldValue = toCase(oldName, profile.keyTable.valueCase);
-            const newValue = toCase(newName, profile.keyTable.valueCase);
-            replaceOps.push({
-                targetPath: keyTablePath,
-                operation: {
-                    kind: 'replace',
-                    find: keysFind,
-                    replaceWith: keysFind
-                        .replace(new RegExp(escapeRegex(oldKey)), newKey)
-                        .replace(new RegExp(`['"]${escapeRegex(oldValue)}['"]`), `'${newValue}'`),
-                    description: `Rename key-table entry ${oldKey} → ${newKey}; '${oldValue}' → '${newValue}'.`,
-                },
-            });
-        }
-        else {
-            conflicts.push(`Key-table entry for "${oldName}" not found in ${keyTablePath}.`);
-        }
-    }
-    // Barrel exports: word/token-bounded matching prevents substring
-    // overlap (e.g. `data` matching inside `dataflow`). A segment match is
-    // valid only when the character after `${segment}/${name}` is NOT a
-    // kebab/identifier continuation character (so `data` doesn't pre-match
-    // `dataflow`, `data-flow`, or `data_flow`).
-    for (const { barrel, content } of ctx.barrels) {
-        if (!content)
-            continue;
-        const segment = barrel.exportSegment ?? 'plugins';
-        const segmentMatchRe = segmentBoundaryRegex(segment, oldName);
-        if (segmentMatchRe.test(content)) {
-            const lines = content.split('\n');
-            for (const line of lines) {
-                // Reset lastIndex so the global regex doesn't skip lines.
-                segmentMatchRe.lastIndex = 0;
-                if (segmentMatchRe.test(line)) {
-                    replaceOps.push({
-                        targetPath: barrel.path,
-                        operation: {
-                            kind: 'replace',
-                            find: line + '\n',
-                            replaceWith: line.replace(segmentBoundaryRegex(segment, oldName), `${segment}/${newName}`) + '\n',
-                            description: `Update barrel export from ${segment}/${oldName} to ${segment}/${newName}.`,
-                        },
-                    });
-                }
-            }
-        }
-        else {
-            conflicts.push(`No barrel export referencing "${segment}/${oldName}" in ${barrel.path}.`);
-        }
-    }
-    // Plugin folder renames — manual unless folder ops requested at the caller
-    const folderOps = [];
-    for (const root of profile.pluginRoots) {
-        const oldDir = join(projectRoot, root.path, oldName);
-        if (existsSync(oldDir)) {
-            if (input.emitFolderOps) {
-                const safety = checkFolderOpSafety(projectRoot, `${root.path}/${oldName}`, 'rename-folder');
-                folderOps.push({
-                    kind: 'rename-folder',
-                    targetPath: `${root.path}/${oldName}`,
-                    newPath: `${root.path}/${newName}`,
-                    safety: safety.safety,
-                    ...(safety.reason ? { safetyReason: safety.reason } : {}),
-                    reason: 'Structured rename-folder op. Apply rejects unsafe paths automatically; humans still review.',
-                });
-            }
-            else {
-                manualSteps.push({
-                    kind: 'rename-folder',
-                    targetPath: `${root.path}/${oldName}`,
-                    newPath: `${root.path}/${newName}`,
-                    reason: 'Rename plugin folder. Plan v2 has no rename-folder op by default; pass `--emit-folder-ops` to include them in the plan.',
-                });
-            }
-        }
-    }
-    return {
-        schema: 'sharkcraft.plugin-lifecycle/v1',
-        action: PluginLifecycleAction.Rename,
-        profile: profile.id,
-        oldName,
-        newName,
-        destructive: manualSteps.length > 0 || folderOps.length > 0,
-        humanApprovalRequired: true,
-        replaceOps,
-        manualSteps,
-        ...(folderOps.length > 0 ? { folderOps } : {}),
-        conflicts,
-        validationCommands: profile.validationCommands ?? [
-            'shrk check boundaries --changed-only',
-            'shrk doctor',
-        ],
-    };
-}
-export function buildPluginRemovePlan(input) {
-    const { projectRoot, profile, oldName } = input;
-    const ctx = loadProfileContext(projectRoot, profile);
-    const replaceOps = [];
-    const manualSteps = [];
-    const folderOps = [];
-    const conflicts = [];
-    if (profile.keyTable && ctx.keyTableContent) {
-        const keyTablePath = profile.keyTable.path;
-        const keysFind = findFirstMatch(ctx.keyTableContent, pluginKeysEntryRegex(profile.keyTable, oldName));
-        if (keysFind) {
-            const oldKey = toCase(oldName, profile.keyTable.keyCase);
-            replaceOps.push({
-                targetPath: keyTablePath,
-                operation: {
-                    kind: 'replace',
-                    find: keysFind,
-                    replaceWith: '',
-                    description: `Remove key-table entry ${oldKey}.`,
-                },
-            });
-        }
-        else {
-            conflicts.push(`Key-table entry for "${oldName}" not found in ${keyTablePath}.`);
-        }
-    }
-    for (const { barrel, content } of ctx.barrels) {
-        if (!content)
-            continue;
-        const segment = barrel.exportSegment ?? 'plugins';
-        const segmentMatchRe = segmentBoundaryRegex(segment, oldName);
-        const lines = content.split('\n');
-        for (const line of lines) {
-            segmentMatchRe.lastIndex = 0;
-            if (segmentMatchRe.test(line)) {
-                replaceOps.push({
-                    targetPath: barrel.path,
-                    operation: {
-                        kind: 'replace',
-                        find: line + '\n',
-                        replaceWith: '',
-                        description: `Remove barrel export referencing ${segment}/${oldName} from ${barrel.path}.`,
-                    },
-                });
-            }
-        }
-    }
-    for (const root of profile.pluginRoots) {
-        const oldDir = join(projectRoot, root.path, oldName);
-        if (existsSync(oldDir)) {
-            if (input.emitFolderOps) {
-                const safety = checkFolderOpSafety(projectRoot, `${root.path}/${oldName}`, 'delete-folder');
-                folderOps.push({
-                    kind: 'delete-folder',
-                    targetPath: `${root.path}/${oldName}`,
-                    safety: safety.safety,
-                    ...(safety.reason ? { safetyReason: safety.reason } : {}),
-                    reason: 'Structured delete-folder op. Apply rejects unsafe paths and requires `--allow-delete-folder`.',
-                });
-            }
-            else {
-                manualSteps.push({
-                    kind: 'delete-folder',
-                    targetPath: `${root.path}/${oldName}`,
-                    reason: 'Delete plugin folder. Destructive; plan v2 has no delete-folder op by default. Use `git rm -r` after the plan is applied, or pass `--emit-folder-ops`.',
-                });
-            }
-        }
-    }
-    return {
-        schema: 'sharkcraft.plugin-lifecycle/v1',
-        action: PluginLifecycleAction.Remove,
-        profile: profile.id,
-        oldName,
-        destructive: true,
-        humanApprovalRequired: true,
-        replaceOps,
-        manualSteps,
-        ...(folderOps.length > 0 ? { folderOps } : {}),
-        conflicts,
-        validationCommands: profile.validationCommands ?? [
-            'shrk check boundaries --changed-only',
-            'shrk doctor',
-        ],
-    };
-}
-/**
- * Convert a plugin-lifecycle plan into a saved plan (synthetic
- * templateId) so it can flow through `shrk apply`. ReplaceOps become
- * `expectedChanges` carrying their operation intent; folderOps[] is copied
- * through. The plan is unsigned by this helper; call `signPlan` separately.
- */
-export const PLUGIN_LIFECYCLE_SYNTHETIC_TEMPLATE = '__plugin-lifecycle__';
-export function pluginLifecyclePlanToSavedPlan(plan, projectRoot) {
-    // Drop redundant no-op replace entries (find == replaceWith).
-    const seen = new Set();
-    const filteredReplaceOps = plan.replaceOps.filter((op) => {
-        if (op.operation.find === op.operation.replaceWith)
-            return false;
-        const key = `${op.targetPath}::${op.operation.find}`;
-        if (seen.has(key))
-            return false;
-        seen.add(key);
-        return true;
-    });
-    // Compute the post-apply file size for each replace op against the
-    // current file, so apply-time divergence detection doesn't false-positive
-    // size-changes against a sentinel value.
-    const expectedChanges = filteredReplaceOps.map((op) => {
-        const abs = join(projectRoot, op.targetPath);
-        let sizeBytes = Buffer.byteLength(op.operation.replaceWith, 'utf8');
-        const existing = readFileSafe(abs);
-        if (existing !== null) {
-            // Compute the size as the file would look after the replace at save
-            // time. Apply will re-evaluate against the (potentially newer) file
-            // and `diffPlanChanges` compares this to the size produced by the
-            // live evaluator.
-            const findCount = (existing.match(new RegExp(escapeRegex(op.operation.find), 'g')) ?? []).length;
-            if (findCount === 1) {
-                const next = existing.replace(op.operation.find, op.operation.replaceWith);
-                sizeBytes = Buffer.byteLength(next, 'utf8');
-            }
-            else {
-                sizeBytes = Buffer.byteLength(existing, 'utf8');
-            }
-        }
-        return {
-            type: 'replace',
-            relativePath: op.targetPath,
-            sizeBytes,
-            operation: op.operation,
-        };
-    });
-    const out = {
-        schema: 'sharkcraft.plan/v2',
-        templateId: PLUGIN_LIFECYCLE_SYNTHETIC_TEMPLATE,
-        variables: {
-            profile: plan.profile,
-            oldName: plan.oldName,
-            ...(plan.newName ? { newName: plan.newName } : {}),
-            action: plan.action,
-        },
-        projectRoot,
-        createdAt: new Date().toISOString(),
-        expectedChanges,
-    };
-    if (plan.folderOps && plan.folderOps.length > 0) {
-        out.folderOps = plan.folderOps.map((fo) => {
-            const entry = {
-                kind: fo.kind,
-                targetPath: fo.targetPath,
-                reason: fo.reason,
-            };
-            if (fo.newPath !== undefined)
-                entry.newPath = fo.newPath;
-            return entry;
-        });
-    }
-    return out;
-}
-export function renderPluginLifecyclePlanText(plan) {
-    const lines = [];
-    lines.push(`=== Plugin ${plan.action} (${plan.profile} profile) ===`);
-    lines.push(`  oldName       ${plan.oldName}`);
-    if (plan.newName)
-        lines.push(`  newName       ${plan.newName}`);
-    lines.push(`  destructive   ${plan.destructive ? 'YES' : 'no'}`);
-    lines.push(`  approval      ${plan.humanApprovalRequired ? 'human review required' : 'auto'}`);
-    lines.push('');
-    lines.push(`Planned replace ops (${plan.replaceOps.length}):`);
-    for (const op of plan.replaceOps) {
-        lines.push(`  • ${op.targetPath}`);
-        lines.push(`      ${op.operation.description}`);
-    }
-    if (plan.manualSteps.length > 0) {
-        lines.push('');
-        lines.push(`Manual steps required (${plan.manualSteps.length}):`);
-        for (const step of plan.manualSteps) {
-            lines.push(`  • [${step.kind}] ${step.targetPath}${step.newPath ? ` → ${step.newPath}` : ''}`);
-            lines.push(`      ${step.reason}`);
-        }
-    }
-    if (plan.conflicts.length > 0) {
-        lines.push('');
-        lines.push(`Conflicts (${plan.conflicts.length}):`);
-        for (const c of plan.conflicts)
-            lines.push(`  • ${c}`);
-    }
-    lines.push('');
-    lines.push(`Validation commands:`);
-    for (const c of plan.validationCommands)
-        lines.push(`  $ ${c}`);
-    return lines.join('\n') + '\n';
-}
-export function buildPluginLifecycleListing(input) {
-    const { projectRoot, profile } = input;
-    const layers = {};
-    for (const root of profile.pluginRoots) {
-        const dir = join(projectRoot, root.path);
-        if (!existsSync(dir))
-            continue;
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        layers[root.path] = entries
-            .filter((e) => e.isDirectory())
-            .map((e) => String(e.name));
-    }
-    const pluginKeys = [];
-    if (profile.keyTable) {
-        const keyTableContent = readFileSafe(join(projectRoot, profile.keyTable.path));
-        if (keyTableContent) {
-            const re = /(^|\n)\s*([A-Za-z_][A-Za-z0-9_]*):\s*'([A-Za-z_][A-Za-z0-9_-]*)'/g;
-            let match;
-            while ((match = re.exec(keyTableContent)) !== null) {
-                pluginKeys.push({ key: match[2], value: match[3] });
-            }
-        }
-    }
-    return { pluginsByLayer: layers, pluginKeys };
-}
-export function checkPluginLifecycleProfileHealth(projectRoot, profile) {
-    const out = [];
-    if (profile.keyTable) {
-        const abs = join(projectRoot, profile.keyTable.path);
-        if (!existsSync(abs)) {
-            out.push({
-                id: 'missing-key-table',
-                severity: 'warning',
-                path: profile.keyTable.path,
-                message: `keyTable.path "${profile.keyTable.path}" not found in this workspace.`,
-            });
-        }
-    }
-    for (const b of profile.barrels ?? []) {
-        if (!existsSync(join(projectRoot, b.path))) {
-            out.push({
-                id: 'missing-barrel',
-                severity: 'warning',
-                path: b.path,
-                message: `Barrel "${b.id}" path "${b.path}" not found.`,
-            });
-        }
-    }
-    for (const r of profile.pluginRoots) {
-        if (!existsSync(join(projectRoot, r.path))) {
-            out.push({
-                id: 'missing-plugin-root',
-                severity: 'warning',
-                path: r.path,
-                message: `Plugin root "${r.id}" path "${r.path}" not found.`,
-            });
-        }
-    }
-    if (out.length === 0) {
-        out.push({
-            id: 'ok',
-            severity: 'info',
-            message: `Profile "${profile.id}" looks healthy in this workspace.`,
-        });
-    }
-    return out;
-}