@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/runtime/capabilityDetector.js

@@ -0,0 +1,443 @@
+// Local runtime capability detector (Issue #1385, Epic #1491). This module is metadata-only:
+// production detection never spawns host executables, never reads Git config, never calls package
+// managers, and never talks to container daemons. It reports coarse, content-free capability states
+// so editor/runtime epics can degrade gracefully without duplicating tool discovery.
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, dirname, parse, relative, resolve } from "node:path";
+import { RUNTIME_CAPABILITY_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { readWorkspaceFile } from "@oscharko-dev/keiko-workspace";
+import { isWithinWorkspace } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+export const DEFAULT_RUNTIME_CAPABILITY_DEADLINE_MS = 250;
+const PACKAGE_READ_BYTES = 262_144;
+export const RUNTIME_HOST_EXECUTABLE_SPECS = Object.freeze([
+    {
+        id: "git",
+        kind: "git",
+        executable: "git",
+        label: "Git",
+        remediationHint: "Install Git or make it available on PATH.",
+    },
+    {
+        id: "node",
+        kind: "node",
+        executable: "node",
+        label: "Node.js",
+        remediationHint: "Install Node.js or make it available on PATH.",
+    },
+    {
+        id: "npm",
+        kind: "package-manager",
+        executable: "npm",
+        label: "npm",
+        remediationHint: "Install npm with Node.js or make it available on PATH.",
+    },
+    {
+        id: "pnpm",
+        kind: "package-manager",
+        executable: "pnpm",
+        label: "pnpm",
+        remediationHint: "Install pnpm or make it available on PATH.",
+    },
+    {
+        id: "yarn",
+        kind: "package-manager",
+        executable: "yarn",
+        label: "Yarn",
+        remediationHint: "Install Yarn or make it available on PATH.",
+    },
+    {
+        id: "python",
+        kind: "language-toolchain",
+        executable: "python3",
+        label: "Python",
+        remediationHint: "Install Python or make python3 available on PATH.",
+    },
+    {
+        id: "java",
+        kind: "language-toolchain",
+        executable: "java",
+        label: "Java",
+        remediationHint: "Install a JDK/JRE or make java available on PATH.",
+    },
+    {
+        id: "go",
+        kind: "language-toolchain",
+        executable: "go",
+        label: "Go",
+        remediationHint: "Install Go or make go available on PATH.",
+    },
+    {
+        id: "rust",
+        kind: "language-toolchain",
+        executable: "rustc",
+        label: "Rust",
+        remediationHint: "Install Rust or make rustc available on PATH.",
+    },
+    {
+        id: "cargo",
+        kind: "language-toolchain",
+        executable: "cargo",
+        label: "Cargo",
+        remediationHint: "Install Cargo or make cargo available on PATH.",
+    },
+    {
+        id: "shellcheck",
+        kind: "language-toolchain",
+        executable: "shellcheck",
+        label: "ShellCheck",
+        remediationHint: "Install ShellCheck or make shellcheck available on PATH.",
+    },
+    {
+        id: "docker",
+        kind: "container-engine",
+        executable: "docker",
+        label: "Docker",
+        remediationHint: "Install Docker or make docker available on PATH.",
+    },
+    {
+        id: "podman",
+        kind: "container-engine",
+        executable: "podman",
+        label: "Podman",
+        remediationHint: "Install Podman or make podman available on PATH.",
+    },
+]);
+function hasUnsafeExecutableName(name) {
+    return (name.length === 0 ||
+        name.includes("\u0000") ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name.includes(" "));
+}
+function executableExtensions(platform, pathext) {
+    if (platform !== "win32") {
+        return [""];
+    }
+    return (pathext ?? ".EXE;.CMD;.BAT;.COM").split(";").filter((value) => value.length > 0);
+}
+function writableByGroupOrOther(mode) {
+    return (mode & 0o022) !== 0;
+}
+function trustedPath(candidate, platform) {
+    if (platform === "win32") {
+        return true;
+    }
+    const file = statSync(candidate);
+    if (!file.isFile() || writableByGroupOrOther(file.mode)) {
+        return false;
+    }
+    const root = parse(candidate).root;
+    let current = dirname(candidate);
+    for (;;) {
+        const info = statSync(current);
+        if (!info.isDirectory() || writableByGroupOrOther(info.mode)) {
+            return false;
+        }
+        if (current === root) {
+            return true;
+        }
+        current = dirname(current);
+    }
+}
+function insideWorkspace(candidate, workspaceRoot, realCandidate) {
+    if (workspaceRoot === undefined) {
+        return false;
+    }
+    let realRoot = workspaceRoot;
+    try {
+        realRoot = nodeWorkspaceFs.realPath(workspaceRoot);
+    }
+    catch {
+        // Fall back to lexical root; missing roots are handled by the route before detector entry.
+    }
+    return isWithinWorkspace(workspaceRoot, candidate) || isWithinWorkspace(realRoot, realCandidate);
+}
+function candidateProbeOutcome(candidate, workspaceRoot, platform) {
+    try {
+        accessSync(candidate, constants.X_OK);
+        const realCandidate = nodeWorkspaceFs.realPath(candidate);
+        if (insideWorkspace(candidate, workspaceRoot, realCandidate) ||
+            !trustedPath(candidate, platform)) {
+            return { found: false, unsafePath: true, permissionDenied: false };
+        }
+        return { found: true, unsafePath: false, permissionDenied: false };
+    }
+    catch (error) {
+        const code = error.code;
+        return {
+            found: false,
+            unsafePath: false,
+            permissionDenied: code === "EACCES" || code === "EPERM",
+        };
+    }
+}
+function unavailableProbeResult(sawUnsafePath, sawPermissionDenied) {
+    if (sawUnsafePath) {
+        return { state: "policy-blocked", unavailableReason: "unsafe-path" };
+    }
+    if (sawPermissionDenied) {
+        return { state: "permission-denied", unavailableReason: "executable-not-runnable" };
+    }
+    return { state: "missing", unavailableReason: "executable-not-found" };
+}
+export class PathHostExecutableProbe {
+    env;
+    platform;
+    constructor(env = process.env, platform = process.platform) {
+        this.env = env;
+        this.platform = platform;
+    }
+    probe(executable, workspaceRoot) {
+        if (hasUnsafeExecutableName(executable)) {
+            return { state: "policy-blocked", unavailableReason: "policy-blocked" };
+        }
+        const pathValue = this.env.PATH ?? "";
+        const extensions = executableExtensions(this.platform, this.env.PATHEXT);
+        let sawPermissionDenied = false;
+        let sawUnsafePath = false;
+        for (const dir of pathValue.split(delimiter).filter(Boolean)) {
+            for (const ext of extensions) {
+                const candidate = resolve(resolve(dir), executable + ext);
+                const outcome = candidateProbeOutcome(candidate, workspaceRoot, this.platform);
+                if (outcome.found) {
+                    return { state: "available" };
+                }
+                sawUnsafePath ||= outcome.unsafePath;
+                sawPermissionDenied ||= outcome.permissionDenied;
+            }
+        }
+        return unavailableProbeResult(sawUnsafePath, sawPermissionDenied);
+    }
+}
+function capabilityFromProbe(spec, result) {
+    const base = {
+        id: spec.id,
+        kind: spec.kind,
+        label: spec.label,
+        ...(result.version === undefined ? {} : { version: result.version }),
+        ...(result.state === "available" ? {} : { remediationHint: spec.remediationHint }),
+    };
+    return {
+        ...base,
+        state: result.state,
+        ...(result.unavailableReason === undefined
+            ? {}
+            : { unavailableReason: result.unavailableReason }),
+    };
+}
+function parseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPackageJson(workspace, fs) {
+    try {
+        return parseJsonObject(readWorkspaceFile(workspace, "package.json", { maxBytes: PACKAGE_READ_BYTES }, fs).text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function packageManagerFromPackageJson(record) {
+    const value = record?.packageManager;
+    if (typeof value !== "string" || value.length === 0 || value.length > 80) {
+        return undefined;
+    }
+    return value.split("@", 1)[0];
+}
+function scriptNames(record) {
+    const scripts = record?.scripts;
+    if (typeof scripts !== "object" || scripts === null || Array.isArray(scripts)) {
+        return [];
+    }
+    return Object.entries(scripts)
+        .filter(([, value]) => typeof value === "string")
+        .map(([name]) => name)
+        .filter((name) => name.length > 0 && name.length <= 120)
+        .sort();
+}
+function isLifecycleWrapper(lowerName, needle) {
+    return (lowerName === `pre${needle}` ||
+        lowerName === `post${needle}` ||
+        lowerName.startsWith(`pre${needle}:`) ||
+        lowerName.startsWith(`post${needle}:`));
+}
+function pickScript(names, exact, contains) {
+    for (const name of names) {
+        if (exact.includes(name.toLowerCase())) {
+            return name;
+        }
+    }
+    for (const name of names) {
+        const lower = name.toLowerCase();
+        if (contains.some((needle) => lower.includes(needle)) &&
+            !contains.some((needle) => isLifecycleWrapper(lower, needle))) {
+            return name;
+        }
+    }
+    return undefined;
+}
+function packageScriptSources(record) {
+    const names = scriptNames(record);
+    const packageManager = packageManagerFromPackageJson(record);
+    const mapping = {
+        test: pickScript(names, ["test"], ["test"]),
+        build: pickScript(names, ["build"], ["build"]),
+        lint: pickScript(names, ["lint"], ["lint", "eslint"]),
+        typecheck: pickScript(names, ["typecheck", "type-check", "tsc"], ["typecheck", "type-check"]),
+    };
+    return Object.entries(mapping)
+        .filter((entry) => entry[1] !== undefined)
+        .map(([commandKind, scriptName]) => ({
+        type: "package-json-script",
+        path: "package.json",
+        commandKind,
+        scriptName,
+        ...(packageManager === undefined ? {} : { packageManager }),
+    }));
+}
+function commandSourceCapability(source) {
+    const label = source.commandKind === undefined
+        ? "Command source"
+        : `${source.commandKind[0]?.toUpperCase() ?? ""}${source.commandKind.slice(1)} command source`;
+    return {
+        id: `command-source:${source.path}:${source.commandKind ?? source.scriptName ?? "manifest"}`,
+        kind: "command-source",
+        label,
+        state: "available",
+        source,
+    };
+}
+function packageManifestCapability(record) {
+    if (record === undefined) {
+        return {
+            id: "manifest:package-json",
+            kind: "command-source",
+            label: "package.json command source",
+            state: "missing",
+            unavailableReason: "manifest-not-found",
+            remediationHint: "Add package.json when Node package scripts should be discoverable.",
+            source: { type: "package-json-script", path: "package.json" },
+        };
+    }
+    return {
+        id: "manifest:package-json",
+        kind: "command-source",
+        label: "package.json command source",
+        state: "available",
+        source: { type: "package-json-script", path: "package.json" },
+    };
+}
+function relativeWorkspacePath(root, absolutePath) {
+    return relative(root, absolutePath).split("\\").join("/");
+}
+function addManifestCapability(capabilities, workspace, fs, path, label) {
+    const absolute = resolve(workspace.root, path);
+    try {
+        if (fs.exists(absolute) && fs.stat(absolute).isFile) {
+            capabilities.push({
+                id: `manifest:${path}`,
+                kind: "command-source",
+                label,
+                state: "available",
+                source: {
+                    type: path.endsWith(".lock") || path.endsWith("lockfile") ? "lockfile" : "ecosystem-manifest",
+                    path: relativeWorkspacePath(workspace.root, absolute),
+                },
+            });
+        }
+    }
+    catch {
+        // Manifest discovery is best-effort and never blocks the endpoint.
+    }
+}
+function workspaceCapabilities(workspace, fs) {
+    if (workspace === undefined) {
+        return [];
+    }
+    const capabilities = [];
+    const packageJson = readPackageJson(workspace, fs);
+    capabilities.push(packageManifestCapability(packageJson));
+    for (const source of packageScriptSources(packageJson)) {
+        capabilities.push(commandSourceCapability(source));
+    }
+    if (packageJson !== undefined && typeof packageJson.packageManager === "string") {
+        capabilities.push({
+            id: "manifest:package-manager",
+            kind: "command-source",
+            label: "package manager declaration",
+            state: "available",
+            source: { type: "ecosystem-manifest", path: "package.json" },
+        });
+    }
+    addManifestCapability(capabilities, workspace, fs, "pnpm-lock.yaml", "pnpm lockfile");
+    addManifestCapability(capabilities, workspace, fs, "yarn.lock", "Yarn lockfile");
+    addManifestCapability(capabilities, workspace, fs, "package-lock.json", "npm lockfile");
+    addManifestCapability(capabilities, workspace, fs, "Cargo.toml", "Rust manifest");
+    addManifestCapability(capabilities, workspace, fs, "go.mod", "Go module manifest");
+    addManifestCapability(capabilities, workspace, fs, "pyproject.toml", "Python project manifest");
+    addManifestCapability(capabilities, workspace, fs, "pom.xml", "Maven manifest");
+    addManifestCapability(capabilities, workspace, fs, "build.gradle", "Gradle manifest");
+    addManifestCapability(capabilities, workspace, fs, "build.gradle.kts", "Gradle Kotlin manifest");
+    addManifestCapability(capabilities, workspace, fs, "Dockerfile", "Dockerfile");
+    return capabilities;
+}
+function deadlineExpired(startedAt, now, deadlineMs) {
+    return now() - startedAt >= deadlineMs;
+}
+function deadlineCapability() {
+    return {
+        id: "runtime-detection:deadline",
+        kind: "command-source",
+        label: "Runtime detection deadline",
+        state: "missing",
+        unavailableReason: "probe-timed-out",
+        remediationHint: "Retry runtime detection or reduce host PATH size.",
+    };
+}
+function detectHostCapabilities(specs, probe, workspaceRoot, generatedAtMs, now, deadlineMs) {
+    const capabilities = [];
+    for (const spec of specs) {
+        if (deadlineExpired(generatedAtMs, now, deadlineMs)) {
+            capabilities.push(deadlineCapability());
+            break;
+        }
+        capabilities.push(capabilityFromProbe(spec, probe.probe(spec.executable, workspaceRoot)));
+    }
+    return capabilities;
+}
+function runtimeProbe(options) {
+    if (options.probe !== undefined) {
+        return options.probe;
+    }
+    return new PathHostExecutableProbe(options.env ?? process.env, options.platform ?? process.platform);
+}
+function appendWorkspaceCapabilities(capabilities, options, fs, generatedAtMs, now, deadlineMs) {
+    if (deadlineExpired(generatedAtMs, now, deadlineMs)) {
+        return;
+    }
+    capabilities.push(...workspaceCapabilities(options.workspace, fs));
+}
+export function detectRuntimeCapabilities(options = {}) {
+    const now = options.now ?? Date.now;
+    const generatedAtMs = now();
+    const deadlineMs = options.deadlineMs ?? DEFAULT_RUNTIME_CAPABILITY_DEADLINE_MS;
+    const fs = options.fs ?? nodeWorkspaceFs;
+    const workspaceRoot = options.workspace?.root;
+    const probe = runtimeProbe(options);
+    const capabilities = detectHostCapabilities(options.specs ?? RUNTIME_HOST_EXECUTABLE_SPECS, probe, workspaceRoot, generatedAtMs, now, deadlineMs);
+    appendWorkspaceCapabilities(capabilities, options, fs, generatedAtMs, now, deadlineMs);
+    return {
+        schemaVersion: RUNTIME_CAPABILITY_SCHEMA_VERSION,
+        generatedAtMs,
+        deadlineMs,
+        capabilities,
+    };
+}

package/dist/runtime/capabilityRoutes.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type RouteContext, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type RuntimeCapabilityDetectorOptions } from "./capabilityDetector.js";
+export type RuntimeCapabilityRouteOptions = Omit<RuntimeCapabilityDetectorOptions, "workspace"> & {
+    readonly detectWorkspace?: ((root: string) => WorkspaceInfo) | undefined;
+};
+export declare function handleRuntimeCapabilities(ctx: RouteContext, deps: UiHandlerDeps, options?: RuntimeCapabilityRouteOptions): Promise<RouteResult>;
+//# sourceMappingURL=capabilityRoutes.d.ts.map

package/dist/runtime/capabilityRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityRoutes.d.ts","sourceRoot":"","sources":["../../src/runtime/capabilityRoutes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAEL,KAAK,gCAAgC,EACtC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,gCAAgC,EAAE,WAAW,CAAC,GAAG;IAChG,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,CAAC,GAAG,SAAS,CAAC;CAC1E,CAAC;AAmBF,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,WAAW,CAAC,CA8BtB"}

package/dist/runtime/capabilityRoutes.js

@@ -0,0 +1,45 @@
+import { detectWorkspaceAt } from "@oscharko-dev/keiko-workspace";
+import { errorBody } from "../routes.js";
+import { resolveRoot, runFilesHandler } from "../files.js";
+import { detectRuntimeCapabilities, } from "./capabilityDetector.js";
+function badRoot() {
+    return {
+        status: 400,
+        body: errorBody("BAD_REQUEST", "The root query parameter must be a non-empty local path."),
+    };
+}
+function workspaceNotRegistered() {
+    return {
+        status: 403,
+        body: errorBody("WORKSPACE_NOT_REGISTERED", "The workspace directory is not a registered project."),
+    };
+}
+export async function handleRuntimeCapabilities(ctx, deps, options = {}) {
+    const rawRoot = ctx.url.searchParams.get("root");
+    if (rawRoot === null) {
+        return {
+            status: 200,
+            body: deps.redactor(detectRuntimeCapabilities({
+                env: deps.env,
+                ...options,
+            })),
+        };
+    }
+    const root = rawRoot.trim();
+    if (root.length === 0) {
+        return badRoot();
+    }
+    if (!deps.store.listProjects().some((project) => project.path === root)) {
+        return workspaceNotRegistered();
+    }
+    return runFilesHandler(async () => {
+        const resolved = await resolveRoot(deps.store, root, deps.redactor);
+        const workspace = (options.detectWorkspace ?? detectWorkspaceAt)(resolved.realRoot);
+        const body = detectRuntimeCapabilities({
+            env: deps.env,
+            ...options,
+            workspace,
+        });
+        return { status: 200, body: deps.redactor(body) };
+    });
+}

package/dist/runtime/containerEngineDetector.d.ts

@@ -0,0 +1,17 @@
+import { runCommand, type SandboxPolicy } from "@oscharko-dev/keiko-tools";
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type ContainerCapabilityResponse, type ContainerEngineId } from "@oscharko-dev/keiko-contracts";
+export declare const DEFAULT_CONTAINER_PROBE_DEADLINE_MS: 4000;
+export declare const SUPPORTED_DOCKER_MAJOR: 20;
+export declare const KEIKO_CONTAINERS_DISABLED_ENV: "KEIKO_CONTAINERS_DISABLED";
+export interface ContainerProbeDeps {
+    readonly runCommand: typeof runCommand;
+    readonly workspace?: WorkspaceInfo | undefined;
+    readonly policy?: SandboxPolicy | undefined;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly now: () => number;
+    readonly deadlineMs?: number | undefined;
+    readonly engines?: readonly ContainerEngineId[] | undefined;
+}
+export declare function detectContainerEngines(deps: ContainerProbeDeps): Promise<ContainerCapabilityResponse>;
+//# sourceMappingURL=containerEngineDetector.d.ts.map

package/dist/runtime/containerEngineDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerEngineDetector.d.ts","sourceRoot":"","sources":["../../src/runtime/containerEngineDetector.ts"],"names":[],"mappings":"AAYA,OAAO,EAIL,UAAU,EAGV,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAIL,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EAIvB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,mCAAmC,EAAG,IAAc,CAAC;AAClE,eAAO,MAAM,sBAAsB,EAAG,EAAW,CAAC;AAElD,eAAO,MAAM,6BAA6B,EAAG,2BAAoC,CAAC;AAqBlF,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,UAAU,EAAE,OAAO,UAAU,CAAC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,GAAG,SAAS,CAAC;CAC7D;AAqMD,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,2BAA2B,CAAC,CA2BtC"}