@litfamily/litopencode 1.0.0

package/dist/cli/native-skill-integrity.d.ts

@@ -0,0 +1,25 @@
+import { litOpenCodeRuntimeSkills } from "../skills.ts";
+import { type ManagedSkillId } from "./managed-skill-assets.ts";
+import { type RetainedCanonicalCache } from "./native-canonical-cache.ts";
+import type { PackageMetadata } from "./types.ts";
+export type RuntimeSkill = (typeof litOpenCodeRuntimeSkills)[number];
+export type DestinationState = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "managed";
+    readonly entrypoint: string;
+} | {
+    readonly kind: "preserved";
+    readonly entrypoint?: string;
+    readonly reason: string;
+};
+export declare function nativeSkillsRoot(root: string): Promise<string>;
+export declare function sourceSkillDir(metadata: PackageMetadata, id: string): string;
+export declare function nativeSkillContent(metadata: PackageMetadata, skill: RuntimeSkill): Promise<string>;
+export declare function validateManagedSkillSource(metadata: PackageMetadata, id: ManagedSkillId): Promise<void>;
+export declare function validateSkillSource(metadata: PackageMetadata, skill: RuntimeSkill): Promise<void>;
+export declare function destinationState(root: string, skill: {
+    readonly id: string;
+}): Promise<DestinationState>;
+export declare function invalidInstalledAssets(skillRoot: string, metadata: PackageMetadata, skill: RuntimeSkill): Promise<string[]>;
+export declare function assertInstalledCanonicalOwnership(root: string, skill: RuntimeSkill): Promise<RetainedCanonicalCache[]>;

package/dist/cli/native-skill-integrity.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { litOpenCodeRuntimeSkills } from "../skills.js";
+import { hasLitOpenCodeGeneratedFileMarker, litOpenCodeGeneratedFrontmatterMarker, stripUserFacingHtmlCommentLines } from "../user-facing-markdown.js";
+import { expectedManagedSkillFiles, expectedInstalledSkillFiles, installedCanonicalDirectory, nativeManagedSkillReferences, isRecursivelyManagedSkill, managedVendorAssets, managedSkillDefinition, managedSkillDiscoveryDescription } from "./managed-skill-assets.js";
+import { assertContained, assertPathComponentsSafe, exactTreeFailures, inventoryTree, lstatIfPresent, resolveSafeDirectory } from "./native-skill-tree.js";
+import { inspectCanonicalTree } from "./native-canonical-cache.js";
+export async function nativeSkillsRoot(root) {
+    return resolveSafeDirectory(root, path.join(root, "skills"), "Native skills destination");
+}
+export function sourceSkillDir(metadata, id) {
+    return path.join(metadata.packageRoot, "skills", id);
+}
+function sourceSkillFile(metadata, id) {
+    return path.join(sourceSkillDir(metadata, id), "SKILL.md");
+}
+function stripYamlFrontmatter(text) {
+    if (!text.startsWith("---\n"))
+        return text;
+    const end = text.indexOf("\n---\n", 4);
+    return end === -1 ? text : text.slice(end + "\n---\n".length);
+}
+export async function nativeSkillContent(metadata, skill) {
+    const source = await fs.readFile(sourceSkillFile(metadata, skill.id), "utf8");
+    const body = nativeManagedSkillReferences(skill.id, stripUserFacingHtmlCommentLines(stripYamlFrontmatter(source))).trimStart();
+    const description = skill.summary + " " + managedSkillDiscoveryDescription(skill.id);
+    return [
+        "---",
+        "name: " + skill.id,
+        "description: |-",
+        ...description.split("\n").map((line) => "  " + line),
+        "metadata:",
+        `  ${litOpenCodeGeneratedFrontmatterMarker.replace(": true", ': "true"')}`,
+        "---",
+        "",
+        body.trimEnd(),
+        ""
+    ].join("\n");
+}
+export async function validateManagedSkillSource(metadata, id) {
+    const skillRoot = sourceSkillDir(metadata, id);
+    await assertPathComponentsSafe(metadata.packageRoot, skillRoot, `Managed source ${id}`);
+    const stat = await lstatIfPresent(skillRoot);
+    if (stat === null || !stat.isDirectory())
+        throw new Error(`Managed source ${id} is not a directory: ${skillRoot}`);
+    const definition = managedSkillDefinition(id);
+    if (definition === undefined)
+        throw new Error(`Managed source manifest is missing ${id}`);
+    const failures = exactTreeFailures(await inventoryTree(skillRoot), expectedManagedSkillFiles(id));
+    if (failures.length > 0)
+        throw new Error(`Managed source ${id} has an altered file set: ${failures.join(", ")}`);
+    const canonicalRoot = definition.canonicalRoot === undefined
+        ? skillRoot
+        : path.resolve(skillRoot, definition.canonicalRoot);
+    await assertPathComponentsSafe(metadata.packageRoot, canonicalRoot, `Managed source ${id} canonical root`);
+    const canonicalStat = await lstatIfPresent(canonicalRoot);
+    if (canonicalStat === null || !canonicalStat.isDirectory()) {
+        throw new Error(`Managed source ${id} canonical root is not a directory: ${canonicalRoot}`);
+    }
+    if (definition.canonicalRoot !== undefined) {
+        const canonicalFailures = exactTreeFailures(await inventoryTree(canonicalRoot), definition.canonicalFiles.map((asset) => asset.path));
+        if (canonicalFailures.length > 0) {
+            throw new Error(`Managed source ${id} canonical tree has an altered file set: ${canonicalFailures.join(", ")}`);
+        }
+    }
+    for (const asset of definition.canonicalFiles) {
+        const actual = createHash("sha256").update(await fs.readFile(path.join(canonicalRoot, asset.path))).digest("hex");
+        if (actual !== asset.sha256) {
+            const sourceLabel = definition.canonicalRoot === undefined ? asset.path : `${definition.canonicalRoot}/${asset.path}`;
+            throw new Error(`Managed source ${id}/${sourceLabel} failed SHA-256: expected ${asset.sha256}, got ${actual}`);
+        }
+    }
+    for (const asset of managedVendorAssets()) {
+        const vendorPath = path.join(metadata.packageRoot, "vendor", asset.path);
+        await assertPathComponentsSafe(metadata.packageRoot, vendorPath, `Managed vendor ${asset.path}`);
+        const actual = createHash("sha256").update(await fs.readFile(vendorPath)).digest("hex");
+        if (actual !== asset.sha256) {
+            throw new Error(`Managed vendor/${asset.path} failed SHA-256: expected ${asset.sha256}, got ${actual}`);
+        }
+    }
+}
+export async function validateSkillSource(metadata, skill) {
+    const skillRoot = sourceSkillDir(metadata, skill.id);
+    await assertPathComponentsSafe(metadata.packageRoot, sourceSkillFile(metadata, skill.id), `Skill source ${skill.id}`);
+    if (isRecursivelyManagedSkill(skill.id)) {
+        await validateManagedSkillSource(metadata, skill.id);
+        return;
+    }
+    const stat = await lstatIfPresent(sourceSkillFile(metadata, skill.id));
+    if (stat === null || !stat.isFile())
+        throw new Error(`Skill source entrypoint is missing: ${sourceSkillFile(metadata, skill.id)}`);
+    const rootStat = await lstatIfPresent(skillRoot);
+    if (rootStat === null || !rootStat.isDirectory())
+        throw new Error(`Skill source root is invalid: ${skillRoot}`);
+}
+export async function destinationState(root, skill) {
+    const skillsRoot = await nativeSkillsRoot(root);
+    const skillRoot = path.join(skillsRoot, skill.id);
+    assertContained(skillsRoot, skillRoot, `Native skill ${skill.id}`);
+    const rootStat = await lstatIfPresent(skillRoot);
+    if (rootStat === null)
+        return { kind: "absent" };
+    if (rootStat.isSymbolicLink())
+        throw new Error(`Native skill ${skill.id} destination is a symbolic link: ${skillRoot}`);
+    if (!rootStat.isDirectory())
+        return { kind: "preserved", reason: "skill root is not a directory" };
+    const entrypoint = path.join(skillRoot, "SKILL.md");
+    const entryStat = await lstatIfPresent(entrypoint);
+    if (entryStat === null)
+        return { kind: "preserved", reason: "pre-existing directory has no managed entrypoint" };
+    if (entryStat.isSymbolicLink())
+        throw new Error(`Native skill ${skill.id} entrypoint is a symbolic link: ${entrypoint}`);
+    if (!entryStat.isFile())
+        return { kind: "preserved", reason: "entrypoint is not a regular file" };
+    if (!hasLitOpenCodeGeneratedFileMarker(await fs.readFile(entrypoint, "utf8"))) {
+        return { kind: "preserved", entrypoint, reason: "entrypoint is user-owned" };
+    }
+    const inventory = await inventoryTree(skillRoot);
+    if (inventory.unsafe.length > 0) {
+        throw new Error(`Native skill ${skill.id} destination contains a symbolic link or special file: ${inventory.unsafe.join(", ")}`);
+    }
+    return { kind: "managed", entrypoint };
+}
+export async function invalidInstalledAssets(skillRoot, metadata, skill) {
+    const inventory = await inventoryTree(skillRoot);
+    if (inventory.unsafe.length > 0)
+        return exactTreeFailures(inventory, expectedInstalledSkillFiles(skill.id));
+    const definition = managedSkillDefinition(skill.id);
+    const canonical = definition?.canonicalRoot === undefined ? undefined : await inspectCanonicalTree(path.join(skillRoot, installedCanonicalDirectory), definition.canonicalFiles).catch(() => ({ failures: [installedCanonicalDirectory], caches: [] }));
+    const caches = canonical?.failures.length === 0 ? canonical.caches : [];
+    const failures = exactTreeFailures(inventory, [
+        ...expectedInstalledSkillFiles(skill.id),
+        ...caches.map((cache) => `${installedCanonicalDirectory}/${cache.path}`)
+    ]);
+    if (canonical !== undefined)
+        failures.push(...canonical.failures.map((file) => `${installedCanonicalDirectory}/${file}`));
+    const expectedEntry = Buffer.from(await nativeSkillContent(metadata, skill));
+    const installedEntry = await fs.readFile(path.join(skillRoot, "SKILL.md"));
+    if (!installedEntry.equals(expectedEntry))
+        failures.push("SKILL.md");
+    if (definition !== undefined) {
+        for (const asset of definition.canonicalFiles) {
+            const relativePath = definition.canonicalRoot === undefined
+                ? asset.path : `${installedCanonicalDirectory}/${asset.path}`;
+            const installed = await fs.readFile(path.join(skillRoot, relativePath)).catch(() => null);
+            const actual = installed === null ? null : createHash("sha256").update(installed).digest("hex");
+            if (actual !== asset.sha256)
+                failures.push(relativePath);
+        }
+        for (const relativePath of definition.distributionFiles.filter((candidate) => candidate !== "SKILL.md")) {
+            const expected = await fs.readFile(path.join(sourceSkillDir(metadata, skill.id), relativePath));
+            const installed = await fs.readFile(path.join(skillRoot, relativePath)).catch(() => null);
+            if (installed === null || !installed.equals(expected))
+                failures.push(relativePath);
+        }
+    }
+    return [...new Set(failures)].sort();
+}
+export async function assertInstalledCanonicalOwnership(root, skill) {
+    const definition = managedSkillDefinition(skill.id);
+    if (definition?.canonicalRoot === undefined)
+        return [];
+    const skillRoot = path.join(await nativeSkillsRoot(root), skill.id);
+    const canonicalRoot = path.join(skillRoot, installedCanonicalDirectory);
+    await assertPathComponentsSafe(skillRoot, canonicalRoot, `Native canonical ${skill.id}`);
+    const stat = await lstatIfPresent(canonicalRoot);
+    // No subtree is the previously shipped flat wrapper, so it can gain its missing closure.
+    if (stat === null)
+        return [];
+    if (!stat.isDirectory())
+        throw new Error(`Native canonical ${skill.id} is not an owned directory`);
+    const { failures, caches } = await inspectCanonicalTree(canonicalRoot, definition.canonicalFiles);
+    if (failures.length > 0) {
+        throw new Error(`Native canonical ${skill.id} contains modified, missing, foreign, or unsafe files; preserve it before retrying: ${failures.join(", ")}`);
+    }
+    return caches;
+}

package/dist/cli/native-skill-tree.d.ts

@@ -0,0 +1,12 @@
+import fs from "node:fs/promises";
+export type TreeInventory = {
+    readonly files: readonly string[];
+    readonly directories: readonly string[];
+    readonly unsafe: readonly string[];
+};
+export declare function lstatIfPresent(filePath: string): Promise<Awaited<ReturnType<typeof fs.lstat>> | null>;
+export declare function assertContained(base: string, target: string, label: string): void;
+export declare function assertPathComponentsSafe(base: string, target: string, label: string): Promise<void>;
+export declare function resolveSafeDirectory(base: string, target: string, label: string): Promise<string>;
+export declare function inventoryTree(root: string): Promise<TreeInventory>;
+export declare function exactTreeFailures(inventory: TreeInventory, expectedFiles: readonly string[]): string[];

package/dist/cli/native-skill-tree.js

@@ -0,0 +1,104 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function lstatIfPresent(filePath) {
+    try {
+        return await fs.lstat(filePath);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export function assertContained(base, target, label) {
+    const relative = path.relative(path.resolve(base), path.resolve(target));
+    if (relative === "" || (!relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative)))
+        return;
+    throw new Error(`${label} escapes its managed root: ${target}`);
+}
+export async function assertPathComponentsSafe(base, target, label) {
+    assertContained(base, target, label);
+    const resolvedBase = path.resolve(base);
+    const resolvedTarget = path.resolve(target);
+    const relative = path.relative(resolvedBase, resolvedTarget);
+    const candidates = [resolvedBase];
+    let current = resolvedBase;
+    if (relative !== "") {
+        for (const component of relative.split(path.sep)) {
+            current = path.join(current, component);
+            candidates.push(current);
+        }
+    }
+    for (const candidate of candidates) {
+        const stat = await lstatIfPresent(candidate);
+        if (stat?.isSymbolicLink())
+            throw new Error(`${label} contains a symbolic link: ${candidate}`);
+    }
+}
+export async function resolveSafeDirectory(base, target, label) {
+    const resolvedTarget = path.resolve(target);
+    assertContained(base, resolvedTarget, label);
+    await assertPathComponentsSafe(base, path.dirname(resolvedTarget), label);
+    const stat = await lstatIfPresent(resolvedTarget);
+    if (stat === null)
+        return resolvedTarget;
+    if (!stat.isSymbolicLink()) {
+        if (!stat.isDirectory())
+            throw new Error(`${label} is not a directory: ${resolvedTarget}`);
+        return resolvedTarget;
+    }
+    const canonicalTarget = await fs.realpath(resolvedTarget);
+    if (!(await fs.stat(canonicalTarget)).isDirectory()) {
+        throw new Error(`${label} symbolic link does not target a directory: ${resolvedTarget}`);
+    }
+    return canonicalTarget;
+}
+export async function inventoryTree(root) {
+    const files = [];
+    const directories = [];
+    const unsafe = [];
+    async function walk(directory, prefix) {
+        for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+            const relative = path.join(prefix, entry.name).split(path.sep).join("/");
+            if (entry.isSymbolicLink()) {
+                unsafe.push(relative);
+            }
+            else if (entry.isDirectory()) {
+                directories.push(relative);
+                await walk(path.join(directory, entry.name), relative);
+            }
+            else if (entry.isFile()) {
+                files.push(relative);
+            }
+            else {
+                unsafe.push(relative);
+            }
+        }
+    }
+    await walk(root, "");
+    return { files: files.sort(), directories: directories.sort(), unsafe: unsafe.sort() };
+}
+export function exactTreeFailures(inventory, expectedFiles) {
+    const failures = [...inventory.unsafe];
+    const actualFiles = new Set(inventory.files);
+    const expectedFileSet = new Set(expectedFiles);
+    const expectedDirectorySet = new Set();
+    for (const file of expectedFiles) {
+        let directory = path.posix.dirname(file);
+        while (directory !== ".") {
+            expectedDirectorySet.add(directory);
+            directory = path.posix.dirname(directory);
+        }
+    }
+    for (const file of expectedFiles)
+        if (!actualFiles.has(file))
+            failures.push(file);
+    for (const file of inventory.files)
+        if (!expectedFileSet.has(file))
+            failures.push(file);
+    for (const directory of inventory.directories) {
+        if (!expectedDirectorySet.has(directory))
+            failures.push(directory + "/");
+    }
+    return [...new Set(failures)].sort();
+}

package/dist/cli/native-skills.d.ts

@@ -0,0 +1,22 @@
+import { inspectScientificVisualizationDependencies } from "./scientific-visualization-dependencies.ts";
+import type { InstallReport, PackageMetadata } from "./types.ts";
+export { validateManagedSkillSource } from "./native-skill-integrity.ts";
+export { ensureNativeSkills } from "./native-skill-install.ts";
+export declare function describeNativeSkillMutation(root: string, metadata: PackageMetadata): Promise<InstallReport["nativeSkills"]>;
+export type NativeSkillInspection = {
+    readonly path: string;
+    readonly expected: readonly string[];
+    readonly present: readonly string[];
+    readonly missing: readonly string[];
+    readonly managed: readonly string[];
+    readonly preserved: readonly string[];
+    readonly invalid: readonly string[];
+    readonly invalidAssets: readonly string[];
+    readonly sourceInvalid: readonly string[];
+    readonly canonicalCacheFiles: readonly string[];
+    readonly dependencies: {
+        readonly "lit-scientific-visualization": ReturnType<typeof inspectScientificVisualizationDependencies>;
+    };
+    readonly ok: boolean;
+};
+export declare function inspectNativeSkills(root: string, metadata: PackageMetadata): Promise<NativeSkillInspection>;

package/dist/cli/native-skills.js

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { litOpenCodeRuntimeSkills } from "../skills.js";
+import { destinationState, assertInstalledCanonicalOwnership, invalidInstalledAssets, validateSkillSource } from "./native-skill-integrity.js";
+import { inspectScientificVisualizationDependencies } from "./scientific-visualization-dependencies.js";
+export { validateManagedSkillSource } from "./native-skill-integrity.js";
+export { ensureNativeSkills } from "./native-skill-install.js";
+export async function describeNativeSkillMutation(root, metadata) {
+    const write = [];
+    const preserve = [];
+    const collisions = [];
+    for (const skill of litOpenCodeRuntimeSkills) {
+        await validateSkillSource(metadata, skill);
+        const destination = await destinationState(root, skill);
+        if (destination.kind === "managed")
+            await assertInstalledCanonicalOwnership(root, skill);
+        if (destination.kind === "absent" || destination.kind === "managed")
+            write.push(skill.id);
+        else {
+            preserve.push(skill.id);
+            if (destination.entrypoint === undefined)
+                collisions.push(skill.id);
+        }
+    }
+    return {
+        path: path.join(root, "skills"),
+        changed: write.length > 0,
+        write,
+        preserve,
+        collisions
+    };
+}
+export async function inspectNativeSkills(root, metadata) {
+    const present = [];
+    const missing = [];
+    const managed = [];
+    const preserved = [];
+    const invalid = [];
+    const invalidAssets = [];
+    const sourceInvalid = [];
+    const canonicalCacheFiles = [];
+    for (const skill of litOpenCodeRuntimeSkills) {
+        let sourceOk = true;
+        try {
+            await validateSkillSource(metadata, skill);
+        }
+        catch (error) {
+            sourceOk = false;
+            sourceInvalid.push(skill.id);
+            invalid.push(skill.id);
+            invalidAssets.push(`${skill.id}/source: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let destination;
+        try {
+            destination = await destinationState(root, skill);
+        }
+        catch (error) {
+            invalid.push(skill.id);
+            invalidAssets.push(`${skill.id}/destination: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (destination.kind === "absent") {
+            missing.push(skill.id);
+            continue;
+        }
+        if (destination.kind === "preserved") {
+            preserved.push(skill.id);
+            if (destination.entrypoint === undefined) {
+                missing.push(skill.id);
+                invalid.push(skill.id);
+                invalidAssets.push(`${skill.id}/SKILL.md`);
+            }
+            else {
+                present.push(skill.id);
+            }
+            continue;
+        }
+        present.push(skill.id);
+        managed.push(skill.id);
+        if (!sourceOk)
+            continue;
+        const failures = await invalidInstalledAssets(path.dirname(destination.entrypoint), metadata, skill);
+        if (failures.length > 0) {
+            invalid.push(skill.id);
+            invalidAssets.push(...failures.map((failure) => `${skill.id}/${failure}`));
+        }
+        else {
+            canonicalCacheFiles.push(...(await assertInstalledCanonicalOwnership(root, skill)).map((cache) => `${skill.id}/canonical/${cache.path}`));
+        }
+    }
+    const uniqueInvalid = [...new Set(invalid)];
+    return {
+        path: path.join(root, "skills"),
+        expected: litOpenCodeRuntimeSkills.map((skill) => skill.id),
+        present,
+        missing,
+        managed,
+        preserved,
+        invalid: uniqueInvalid,
+        invalidAssets: [...new Set(invalidAssets)],
+        sourceInvalid,
+        canonicalCacheFiles,
+        dependencies: { "lit-scientific-visualization": inspectScientificVisualizationDependencies() },
+        ok: missing.length === 0 && uniqueInvalid.length === 0
+    };
+}

package/dist/cli/plugin-mutation.d.ts

@@ -0,0 +1,4 @@
+import type { PluginMutation } from "./types.ts";
+export declare function isLitOpenCodeEntry(value: unknown): boolean;
+export declare function describePluginMutation(config: Record<string, unknown> | null, target: string): PluginMutation;
+export declare function applyPluginMutation(config: Record<string, unknown> | null, mutation: PluginMutation, target: string): Record<string, unknown>;

package/dist/cli/plugin-mutation.js

@@ -0,0 +1,89 @@
+export function isLitOpenCodeEntry(value) {
+    const id = pluginEntryId(value);
+    return ["litopencode", "@litfamily/opencode", "@litfamily/litopencode"].some((name) => id === name || id.startsWith(`${name}@`));
+}
+function pluginEntryId(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && typeof value[0] === "string")
+        return value[0];
+    return "";
+}
+function replaceLitOpenCodeEntry(value, target) {
+    if (Array.isArray(value) && isLitOpenCodeEntry(value))
+        return [target, ...value.slice(1)];
+    return target;
+}
+function normalizedPluginArray(pluginValue, target) {
+    const firstLitEntry = pluginValue.find(isLitOpenCodeEntry);
+    const replacement = firstLitEntry === undefined ? target : replaceLitOpenCodeEntry(firstLitEntry, target);
+    let replaced = false;
+    const next = [];
+    for (const value of pluginValue) {
+        if (!isLitOpenCodeEntry(value)) {
+            next.push(value);
+            continue;
+        }
+        if (replaced)
+            continue;
+        next.push(replacement);
+        replaced = true;
+    }
+    return next;
+}
+export function describePluginMutation(config, target) {
+    const pluginValue = config?.plugin;
+    const pluginIsArray = Array.isArray(pluginValue);
+    const existingIndex = pluginIsArray ? pluginValue.findIndex(isLitOpenCodeEntry) : -1;
+    const targetIndex = pluginIsArray ? pluginValue.findIndex((value) => pluginEntryId(value) === target) : -1;
+    const litEntryCount = pluginIsArray ? pluginValue.filter(isLitOpenCodeEntry).length : 0;
+    const alreadyPresent = targetIndex >= 0 && litEntryCount === 1;
+    const currentCount = pluginIsArray ? pluginValue.length : 0;
+    if (alreadyPresent) {
+        return {
+            changed: false,
+            plugin: { alreadyPresent: true, currentCount, resultCount: currentCount, add: [] },
+            patch: []
+        };
+    }
+    const add = [target];
+    if (pluginIsArray) {
+        if (existingIndex >= 0) {
+            if (litEntryCount > 1) {
+                return {
+                    changed: true,
+                    plugin: { alreadyPresent: targetIndex >= 0, currentCount, resultCount: currentCount - litEntryCount + 1, add },
+                    patch: [{ op: "replace", path: "/plugin", value: normalizedPluginArray(pluginValue, target) }]
+                };
+            }
+            return {
+                changed: true,
+                plugin: { alreadyPresent: true, currentCount, resultCount: currentCount, add },
+                patch: [{ op: "replace", path: `/plugin/${existingIndex}`, value: replaceLitOpenCodeEntry(pluginValue[existingIndex], target) }]
+            };
+        }
+        return {
+            changed: true,
+            plugin: { alreadyPresent: false, currentCount, resultCount: currentCount + 1, add },
+            patch: [{ op: "add", path: "/plugin/-", value: target }]
+        };
+    }
+    const op = config !== null && Object.hasOwn(config, "plugin") ? "replace" : "add";
+    return {
+        changed: true,
+        plugin: { alreadyPresent: false, currentCount, resultCount: 1, add },
+        patch: [{ op, path: "/plugin", value: [target] }]
+    };
+}
+export function applyPluginMutation(config, mutation, target) {
+    const next = config === null ? { "$schema": "https://opencode.ai/config.json" } : { ...config };
+    if (!mutation.changed)
+        return next;
+    const pluginValue = next.plugin;
+    if (Array.isArray(pluginValue)) {
+        next.plugin = pluginValue.some(isLitOpenCodeEntry) ? normalizedPluginArray(pluginValue, target) : [...pluginValue, target];
+        return next;
+    }
+    next.plugin = [target];
+    return next;
+}

package/dist/cli/scientific-visualization-dependencies.d.ts

@@ -0,0 +1,18 @@
+export type ScientificVisualizationDependencyReport = {
+    readonly status: "READY" | "DEGRADED";
+    readonly interpreter: {
+        readonly command: string;
+        readonly available: boolean;
+        readonly version?: string;
+    };
+    readonly required: {
+        readonly available: readonly string[];
+        readonly missing: readonly string[];
+    };
+    readonly optional: {
+        readonly available: readonly string[];
+        readonly missing: readonly string[];
+    };
+    readonly autoInstall: false;
+};
+export declare function inspectScientificVisualizationDependencies(): ScientificVisualizationDependencyReport;

package/dist/cli/scientific-visualization-dependencies.js

@@ -0,0 +1,91 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+const requiredModules = Object.freeze(["matplotlib"]);
+const optionalModules = Object.freeze([
+    "numpy",
+    "seaborn",
+    "pandas",
+    "plotly",
+    "scipy",
+    "colorspacious",
+    "MDAnalysis",
+    "kaleido"
+]);
+function selectedInterpreter() {
+    const explicit = process.env.LITOPENCODE_SCIENTIFIC_PYTHON?.trim();
+    return explicit && explicit.length > 0 ? explicit : "python3";
+}
+function unavailableReport(command) {
+    return {
+        status: "DEGRADED",
+        interpreter: { command, available: false },
+        required: { available: [], missing: [command, ...requiredModules] },
+        optional: { available: [], missing: optionalModules },
+        autoInstall: false
+    };
+}
+function availableNames(names, modules) {
+    return names.filter((name) => modules[name] === true);
+}
+function missingNames(names, modules) {
+    return names.filter((name) => modules[name] !== true);
+}
+export function inspectScientificVisualizationDependencies() {
+    const command = selectedInterpreter();
+    const modules = [...requiredModules, ...optionalModules];
+    const script = [
+        "import importlib, json, platform",
+        `modules = ${JSON.stringify(modules)}`,
+        "def can_import(name):",
+        "    try:",
+        "        importlib.import_module(name)",
+        "        return True",
+        "    except Exception:",
+        "        return False",
+        "print(json.dumps({'version': platform.python_version(), 'modules': {name: can_import(name) for name in modules}}))"
+    ].join("\n");
+    const matplotlibConfig = mkdtempSync(path.join(tmpdir(), "litopencode-matplotlib-probe-"));
+    let result;
+    try {
+        result = spawnSync(command, ["-c", script], {
+            encoding: "utf8",
+            timeout: 15_000,
+            env: {
+                ...process.env,
+                MPLCONFIGDIR: matplotlibConfig,
+                PYTHONDONTWRITEBYTECODE: "1"
+            }
+        });
+    }
+    finally {
+        rmSync(matplotlibConfig, { recursive: true, force: true });
+    }
+    if (result.status !== 0 || result.error !== undefined)
+        return unavailableReport(command);
+    try {
+        const parsed = JSON.parse(String(result.stdout));
+        if (typeof parsed.version !== "string" || !parsed.modules || typeof parsed.modules !== "object") {
+            return unavailableReport(command);
+        }
+        const availability = parsed.modules;
+        const requiredMissing = missingNames(requiredModules, availability);
+        return {
+            status: requiredMissing.length === 0 ? "READY" : "DEGRADED",
+            interpreter: { command, available: true, version: parsed.version },
+            required: {
+                available: availableNames(requiredModules, availability),
+                missing: requiredMissing
+            },
+            optional: {
+                available: availableNames(optionalModules, availability),
+                missing: missingNames(optionalModules, availability)
+            },
+            autoInstall: false
+        };
+    }
+    catch {
+        return unavailableReport(command);
+    }
+}

package/dist/cli/skill-loop.d.ts

@@ -0,0 +1,3 @@
+import type { CliResult } from "./types.ts";
+export declare function runSkillLoopCli(argv: readonly string[]): Promise<CliResult>;
+export declare function runSkillCuratorCli(argv: readonly string[]): Promise<CliResult>;