ast-mcp-server 0.9.2 → 0.11.0

package/dist/services/skill-installer.js

@@ -2,7 +2,8 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
-import { applyManagedFilePlan, canonicalizeFuturePath, captureManagedFileSnapshot, createManagedFileApplyContext, hashBytes, verifyManagedFilePostimage, } from "./managed-file.js";
+import { canonicalizeFuturePath, createManagedFileApplyContext, } from "./managed-file.js";
+import { applyManagedBundle, ManagedBundleConflictError, planManagedBundle, } from "./managed-bundle.js";
 const SKILL_NAME = "structural-code-editing";
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const ReleaseRecordSchema = z
@@ -12,17 +13,24 @@ const ReleaseRecordSchema = z
     npm_versions: z.array(z.string().min(1)).min(1),
 })
     .strict();
-const SkillReleaseManifestSchema = z
+const SkillFileSchema = z
+    .object({ path: z.string().min(1), sha256: z.string().regex(SHA256_PATTERN) })
+    .strict();
+const BundleReleaseSchema = z
+    .object({
+    version: z.string().min(1),
+    files: z.array(SkillFileSchema).min(1),
+})
+    .strict();
+const BundleSkillReleaseManifestSchema = z
     .object({
-    schema_version: z.literal(1),
+    schema_version: z.literal(2),
     algorithm: z.literal("sha256"),
-    current: z
-        .object({
-        version: z.string().min(1),
-        sha256: z.string().regex(SHA256_PATTERN),
-    })
-        .strict(),
-    predecessors: z.array(ReleaseRecordSchema),
+    current: BundleReleaseSchema,
+    predecessors: z.array(z.union([
+        ReleaseRecordSchema,
+        BundleReleaseSchema.extend({ npm_versions: z.array(z.string().min(1)).min(1) }),
+    ])),
 })
     .strict();
 export class SkillConflictError extends Error {
@@ -101,77 +109,87 @@ async function readReleaseManifest(manifestPath) {
     catch (error) {
         throw new Error(`Skill release manifest is unreadable or invalid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
-    const result = SkillReleaseManifestSchema.safeParse(parsed);
+    const result = BundleSkillReleaseManifestSchema.safeParse(parsed);
     if (!result.success) {
         throw new Error(`Skill release manifest is invalid: ${result.error.issues[0]?.message ?? "unknown error"}`);
     }
-    const digests = [
-        result.data.current.sha256,
-        ...result.data.predecessors.map((item) => item.sha256),
-    ];
-    if (new Set(digests).size !== digests.length) {
-        throw new Error("Skill release manifest contains a duplicate digest.");
+    const manifest = {
+        current: result.data.current,
+        predecessors: result.data.predecessors.map((item) => "files" in item
+            ? item
+            : {
+                version: item.version,
+                npm_versions: item.npm_versions,
+                files: [{ path: "SKILL.md", sha256: item.sha256 }],
+            }),
+    };
+    if (!manifest.current.files.some((file) => file.path === "SKILL.md")) {
+        throw new Error("Skill release manifest current bundle must include SKILL.md.");
     }
     const predecessorVersions = result.data.predecessors.flatMap((item) => item.npm_versions);
     if (new Set(predecessorVersions).size !== predecessorVersions.length) {
         throw new Error("Skill release manifest contains a duplicate npm version provenance entry.");
     }
-    return result.data;
+    return manifest;
 }
 export async function planBundledSkillInstallation(options) {
     const sourcePath = path.resolve(options.sourceSkillPath);
-    const source = await readFile(sourcePath);
-    const sourceDigest = hashBytes(source);
-    const manifestPath = path.resolve(options.releaseManifestPath ?? path.join(path.dirname(sourcePath), "releases.json"));
+    const sourceRoot = path.dirname(sourcePath);
+    const canonicalSourceRoot = await realpath(sourceRoot);
+    const manifestPath = path.resolve(options.releaseManifestPath ?? path.join(sourceRoot, "releases.json"));
     const manifest = await readReleaseManifest(manifestPath);
-    if (sourceDigest !== manifest.current.sha256) {
-        throw new Error(`Skill release manifest current digest does not match source skill bytes: ${sourcePath}`);
+    const sources = [];
+    for (const file of manifest.current.files) {
+        const assetPath = path.resolve(sourceRoot, file.path);
+        const assetRealPath = await realpath(assetPath).catch(() => undefined);
+        if (assetRealPath === undefined ||
+            (assetRealPath !== canonicalSourceRoot &&
+                !assetRealPath.startsWith(`${canonicalSourceRoot}${path.sep}`)) ||
+            !(await stat(assetPath)).isFile()) {
+            throw new Error(`Skill release manifest asset is missing or escapes the bundle: ${file.path}`);
+        }
+        sources.push({ ...file, content: await readFile(assetPath) });
     }
-    const admittedPredecessors = new Set(manifest.predecessors.map((item) => item.sha256));
     const logical = await destinations(options);
     const filesByPath = new Map();
+    const statusesByRoot = new Map();
     for (const item of logical) {
-        if (filesByPath.has(item.path))
+        const destinationRoot = path.dirname(item.path);
+        if (statusesByRoot.has(destinationRoot))
             continue;
-        const snapshot = await captureManagedFileSnapshot(item.path);
-        let status;
-        if (!snapshot.exists)
-            status = "installed";
-        else if (snapshot.sha256 === sourceDigest)
-            status = "unchanged";
-        else if (admittedPredecessors.has(snapshot.sha256) || options.force === true)
-            status = "updated";
-        else
-            throw new SkillConflictError(item.path);
-        filesByPath.set(item.path, {
-            path: item.path,
-            snapshot,
-            postimage: source,
-            postimageSha256: sourceDigest,
-            status,
-        });
+        let plan;
+        try {
+            plan = await planManagedBundle({
+                destinationRoot,
+                current: { files: sources },
+                predecessors: manifest.predecessors,
+                force: options.force,
+            });
+        }
+        catch (error) {
+            if (error instanceof ManagedBundleConflictError)
+                throw new SkillConflictError(error.destination);
+            if (error instanceof Error && error.message.startsWith("Managed bundle")) {
+                throw new Error(error.message.replace("Managed bundle", "Skill release manifest"), {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+        statusesByRoot.set(destinationRoot, plan.status);
+        for (const file of plan.files)
+            filesByPath.set(file.path, file);
     }
     return {
         installations: logical.map((item) => ({
             ...item,
-            status: filesByPath.get(item.path).status,
+            status: statusesByRoot.get(path.dirname(item.path)),
         })),
         files: [...filesByPath.values()],
     };
 }
-export async function applySkillInstallationPlan(plan, onApplied, context = createManagedFileApplyContext()) {
-    const authenticated = [];
-    for (const file of plan.files) {
-        for (const current of authenticated) {
-            await verifyManagedFilePostimage(current, context);
-        }
-        await applyManagedFilePlan(file, context);
-        authenticated.push(file);
-        await onApplied?.(file);
-    }
-    for (const current of authenticated) {
-        await verifyManagedFilePostimage(current, context);
-    }
+export async function applySkillInstallationPlan(plan, onApplied, context = createManagedFileApplyContext(), hooks = {}) {
+    await applyManagedBundle(plan, onApplied, context, hooks);
 }
 export async function installBundledSkill(options) {
     const plan = await planBundledSkillInstallation(options);

package/dist/services/test-candidates.js

@@ -4,21 +4,22 @@ export const DEFAULT_TEST_DIRECTORIES = Object.freeze(["test", "tests", "__tests
 export const TEST_CANDIDATE_REASONS = Object.freeze([
     "direct_compiler_reference",
     "transitive_compiler_reference",
+    "convention_match",
 ]);
 export const TEST_CANDIDATE_CONFIDENCES = Object.freeze(["exact", "high"]);
-const MAX_CONVENTION_ITEMS = 32;
-const MAX_CONVENTION_LENGTH = 256;
+export const MAX_TEST_CANDIDATE_CONVENTION_ITEMS = 32;
+export const MAX_TEST_CANDIDATE_CONVENTION_LENGTH = 256;
 function normalizeConventionValues(values, defaults, label) {
     const selected = values ?? defaults;
-    if (!Array.isArray(selected) || selected.length > MAX_CONVENTION_ITEMS) {
-        throw new Error(`${label} must contain at most ${MAX_CONVENTION_ITEMS} entries.`);
+    if (!Array.isArray(selected) || selected.length > MAX_TEST_CANDIDATE_CONVENTION_ITEMS) {
+        throw new Error(`${label} must contain at most ${MAX_TEST_CANDIDATE_CONVENTION_ITEMS} entries.`);
     }
     const normalized = selected.map((value) => {
         if (typeof value !== "string" || value.trim().length === 0) {
             throw new Error(`${label} entries must be non-empty strings.`);
         }
-        if (value.length > MAX_CONVENTION_LENGTH) {
-            throw new Error(`${label} entries must not exceed ${MAX_CONVENTION_LENGTH} characters.`);
+        if (value.length > MAX_TEST_CANDIDATE_CONVENTION_LENGTH) {
+            throw new Error(`${label} entries must not exceed ${MAX_TEST_CANDIDATE_CONVENTION_LENGTH} characters.`);
         }
         return value.trim().replaceAll("\\", "/");
     });
@@ -112,7 +113,13 @@ function edgeOrder(left, right) {
         left.target.file.localeCompare(right.target.file) ||
         left.target.selector.localeCompare(right.target.selector));
 }
-function candidateReason(depth) {
+function candidateReason(file, depth) {
+    if (!isTestFile(file, {
+        patterns: DEFAULT_TEST_FILE_PATTERNS,
+        directories: DEFAULT_TEST_DIRECTORIES,
+    })) {
+        return "convention_match";
+    }
     return depth === 1 ? "direct_compiler_reference" : "transitive_compiler_reference";
 }
 function candidateConfidence(depth) {
@@ -194,7 +201,7 @@ export function findTestCandidates(impact, conventions = {}) {
         const depth = candidate.depth;
         return {
             file,
-            reason: candidateReason(depth),
+            reason: candidateReason(file, depth),
             confidence: candidateConfidence(depth),
             evidence: {
                 depth,

package/dist/services/upgrade-command.js

@@ -0,0 +1,77 @@
+import { inspectUpgrade, performUpgrade, UpgradeError } from "./upgrade.js";
+import { ReconciliationError } from "./upgrade-reconcile.js";
+import { UpgradeCleanupError } from "./upgrade-runtime.js";
+export class UpgradeCommandError extends Error {
+    code;
+    constructor(code = "UPGRADE_USAGE") {
+        super("Usage: ast-tool upgrade [--check]");
+        this.code = code;
+        this.name = "UpgradeCommandError";
+    }
+}
+export async function runUpgradeCommand(args, runtime, reconcile) {
+    if (args.length > 1 || (args.length === 1 && args[0] !== "--check")) {
+        throw new UpgradeCommandError();
+    }
+    if (args[0] === "--check")
+        return inspectUpgrade(runtime);
+    const updated = await performUpgrade(runtime);
+    const { new_cli: newCli, ...result } = updated;
+    if (updated.status === "current")
+        return { ...result, reconciliation: "not_required" };
+    try {
+        await reconcile(newCli);
+        return { ...result, reconciliation: "completed" };
+    }
+    catch (error) {
+        const skillConflict = error instanceof ReconciliationError && error.code === "AGENT_SKILL_CONFLICT";
+        return {
+            ...result,
+            status: "partial",
+            package_status: "updated",
+            reconciliation: "required",
+            continuation: skillConflict
+                ? "ast-tool setup --agents all --yes --force-skill"
+                : "ast-tool setup --agents all --yes",
+            restart_required: true,
+        };
+    }
+}
+function primaryCode(error) {
+    return error instanceof UpgradeError || error instanceof UpgradeCommandError
+        ? error.code
+        : "UPGRADE_ERROR";
+}
+export async function runUpgradeLease(args, lease, reconcile) {
+    let result;
+    let primary;
+    try {
+        result = await runUpgradeCommand(args, lease.runtime, reconcile);
+    }
+    catch (error) {
+        primary = error;
+    }
+    try {
+        await lease.dispose();
+    }
+    catch {
+        if (primary)
+            throw new UpgradeCleanupError(primaryCode(primary));
+        const record = result;
+        if (record.status === "updated" || record.package_status === "updated") {
+            return {
+                ...record,
+                status: "partial",
+                package_status: "updated",
+                cleanup: "required",
+                cleanup_code: "UPGRADE_CLEANUP_FAILED",
+                continuation: record.continuation ?? "ast-tool upgrade --check",
+                restart_required: true,
+            };
+        }
+        throw new UpgradeCleanupError();
+    }
+    if (primary)
+        throw primary;
+    return result;
+}

package/dist/services/upgrade-reconcile.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import process from "node:process";
+import { promisify } from "node:util";
+const executeFile = promisify(execFile);
+export class ReconciliationError extends Error {
+    code;
+    constructor(code) {
+        super("The updated package requires managed setup reconciliation.");
+        this.code = code;
+        this.name = "ReconciliationError";
+    }
+}
+export async function reconcileUpgrade(executable, options = {}) {
+    const execute = options.execute ?? executeFile;
+    try {
+        await execute(options.nodeExecutable ?? process.execPath, [executable, "setup", "--agents", "all", "--yes"], {
+            encoding: "utf8",
+            windowsHide: true,
+            env: options.environment ?? process.env,
+        });
+    }
+    catch (error) {
+        const stderr = typeof error === "object" && error !== null && "stderr" in error
+            ? String(error.stderr ?? "")
+            : "";
+        try {
+            const failure = JSON.parse(stderr);
+            if (typeof failure === "object" &&
+                failure !== null &&
+                "code" in failure &&
+                failure.code === "AGENT_SKILL_CONFLICT") {
+                throw new ReconciliationError("AGENT_SKILL_CONFLICT");
+            }
+        }
+        catch (parsed) {
+            if (parsed instanceof ReconciliationError)
+                throw parsed;
+        }
+        throw new ReconciliationError("UPGRADE_RECONCILIATION_FAILED");
+    }
+}

package/dist/services/upgrade-runtime.js

@@ -0,0 +1,157 @@
+import { execFile } from "node:child_process";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+export class UpgradeCleanupError extends Error {
+    primaryCode;
+    code = "UPGRADE_CLEANUP_FAILED";
+    constructor(primaryCode) {
+        super("Upgrade temporary files could not be removed safely.");
+        this.primaryCode = primaryCode;
+        this.name = "UpgradeCleanupError";
+    }
+}
+const executeFile = promisify(execFile);
+async function npmCliFor(node, platform) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const root = platform === "win32" ? p.dirname(node) : p.resolve(p.dirname(node), "..");
+    const candidates = platform === "win32"
+        ? [p.join(root, "node_modules", "npm", "bin", "npm-cli.js")]
+        : [
+            p.join(p.dirname(node), "npm"),
+            p.join(root, "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        ];
+    for (const candidate of candidates) {
+        try {
+            const resolved = await realpath(candidate);
+            if ((await lstat(resolved)).isFile())
+                return resolved;
+        }
+        catch {
+            // Try the next layout owned by this Node installation.
+        }
+    }
+    return;
+}
+async function copyUserConfig(environment, destination) {
+    const source = environment.npm_config_userconfig ??
+        environment.NPM_CONFIG_USERCONFIG ??
+        path.join(environment.HOME ?? os.homedir(), ".npmrc");
+    try {
+        await copyFile(source, destination);
+        await chmod(destination, 0o600);
+    }
+    catch {
+        await writeFile(destination, "", { encoding: "utf8", mode: 0o600 });
+    }
+}
+async function restoreOwnerAccess(value) {
+    const info = await lstat(value);
+    if (info.isSymbolicLink())
+        return;
+    await chmod(value, info.isDirectory() ? 0o700 : 0o600);
+    if (info.isDirectory())
+        for (const child of await readdir(value))
+            await restoreOwnerAccess(path.join(value, child));
+}
+async function cleanupBoundary(boundary, removeTree = (value) => rm(value, { recursive: true, force: true })) {
+    try {
+        await restoreOwnerAccess(boundary);
+        await removeTree(boundary);
+    }
+    catch {
+        throw new UpgradeCleanupError();
+    }
+    try {
+        await lstat(boundary);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new UpgradeCleanupError();
+    }
+    throw new UpgradeCleanupError();
+}
+export async function createUpgradeRuntime(executable, options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const nodeExecutable = options.nodeExecutable ?? process.execPath;
+    const execute = options.execute ?? executeFile;
+    const boundary = await mkdtemp(path.join(options.temporaryParent ?? os.tmpdir(), "ast-tool-upgrade-"));
+    try {
+        const cache = path.join(boundary, "cache");
+        const logs = path.join(boundary, "logs");
+        const userConfig = path.join(boundary, "npmrc");
+        await Promise.all([mkdir(cache), mkdir(logs), copyUserConfig(environment, userConfig)]);
+        const npmEnvironment = {
+            ...environment,
+            npm_config_cache: cache,
+            npm_config_logs_dir: logs,
+            npm_config_userconfig: userConfig,
+            npm_config_update_notifier: "false",
+            npm_config_audit: "false",
+            npm_config_fund: "false",
+        };
+        const run = async (file, args) => (await execute(file, args, { encoding: "utf8", windowsHide: true, env: npmEnvironment }))
+            .stdout;
+        const cliExecutable = await realpath(executable);
+        const packageRoot = path.resolve(path.dirname(cliExecutable), "..");
+        const npmCliExecutable = await npmCliFor(nodeExecutable, platform);
+        const p = platform === "win32" ? path.win32 : path.posix;
+        const voltaExecutable = environment.VOLTA_HOME
+            ? p.resolve(environment.VOLTA_HOME, "bin", platform === "win32" ? "volta.exe" : "volta")
+            : undefined;
+        const runtime = {
+            packageRoot,
+            cliExecutable,
+            nodeExecutable,
+            ...(npmCliExecutable ? { npmCliExecutable } : {}),
+            ...(voltaExecutable ? { voltaExecutable } : {}),
+            platform,
+            realpath,
+            directDirectory: async (value) => {
+                const info = await lstat(value).catch(() => undefined);
+                return info?.isDirectory() === true && info.isSymbolicLink() === false;
+            },
+            readPackage: async (root) => JSON.parse(await readFile(path.join(root, "package.json"), "utf8")),
+            latestVersion: async (provenance) => {
+                const stdout = provenance === "volta"
+                    ? await run(voltaExecutable, [
+                        "run",
+                        "npm",
+                        "view",
+                        "ast-mcp-server@latest",
+                        "version",
+                        "--json",
+                    ])
+                    : await run(nodeExecutable, [
+                        npmCliExecutable,
+                        "view",
+                        "ast-mcp-server@latest",
+                        "version",
+                        "--json",
+                    ]);
+                const value = JSON.parse(stdout);
+                if (typeof value !== "string")
+                    throw new Error("invalid registry response");
+                return value;
+            },
+            run,
+        };
+        return {
+            runtime,
+            dispose: () => cleanupBoundary(boundary, options.removeTree),
+        };
+    }
+    catch (error) {
+        try {
+            await cleanupBoundary(boundary, options.removeTree);
+        }
+        catch {
+            throw new UpgradeCleanupError("UPGRADE_RUNTIME_CREATION_FAILED");
+        }
+        throw error;
+    }
+}