@dailephd/my-dev-kit-lab 0.2.0

package/dist/src/commands/runVisualizationDemosCommand.js

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { runVisualizationDemos } from "../visualizationDemos/index.js";
+export function parseRunVisualizationDemosArgs(argv) {
+    let projectPath = "";
+    let kitCommand = "";
+    let outDir = "";
+    let query;
+    let nodeId;
+    let requireAll = false;
+    let timeoutMs;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--project") {
+            projectPath = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--kit-command") {
+            kitCommand = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--out") {
+            outDir = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--query") {
+            query = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--node") {
+            nodeId = argv[index + 1] ?? "";
+            index += 1;
+        }
+        else if (arg === "--require-all") {
+            requireAll = true;
+        }
+        else if (arg === "--timeout-ms") {
+            timeoutMs = Number(argv[index + 1]);
+            index += 1;
+        }
+    }
+    if (!projectPath || !kitCommand || !outDir)
+        throw new Error("Usage: --project <dir> --kit-command <command> --out <dir>");
+    return { projectPath, kitCommand, outDir, query, nodeId, requireAll, timeoutMs };
+}
+export async function runVisualizationDemosFromArgs(args, repoRoot = process.cwd()) {
+    return runVisualizationDemos({
+        projectPath: path.resolve(repoRoot, args.projectPath),
+        kitCommand: args.kitCommand,
+        outDir: path.resolve(repoRoot, args.outDir),
+        query: args.query,
+        nodeId: args.nodeId,
+        requireAll: args.requireAll,
+        timeoutMs: args.timeoutMs
+    });
+}
+export async function runVisualizationDemosCommand(argv) {
+    try {
+        const args = parseRunVisualizationDemosArgs(argv);
+        const artifacts = await runVisualizationDemosFromArgs(args);
+        console.log([`Runs: ${artifacts.summary.totalRuns}`, `Completed: ${artifacts.summary.completedRuns}`, `Failed: ${artifacts.summary.failedRuns}`, `Output: ${path.resolve(args.outDir)}`].join("\n"));
+        return args.requireAll && artifacts.summary.failedRuns > 0 ? 1 : 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}

package/dist/src/core/commandLine.js

@@ -0,0 +1,59 @@
+export function parseCommandString(command) {
+    const parts = splitCommandString(command);
+    if (parts.length === 0) {
+        throw new Error("Command string is empty.");
+    }
+    return {
+        executable: parts[0],
+        args: parts.slice(1)
+    };
+}
+export function splitCommandString(command) {
+    const parts = [];
+    let current = "";
+    let quote = null;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        const next = command[index + 1];
+        if (char === "\\" && quote !== null && next === quote) {
+            current += next;
+            index += 1;
+            continue;
+        }
+        if ((char === "\"" || char === "'") && quote === null) {
+            quote = char;
+            continue;
+        }
+        if (char === quote) {
+            quote = null;
+            continue;
+        }
+        if (/\s/.test(char) && quote === null) {
+            if (current.length > 0) {
+                parts.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (quote !== null) {
+        throw new Error(`Command string has an unmatched ${quote} quote.`);
+    }
+    if (current.length > 0) {
+        parts.push(current);
+    }
+    return parts;
+}
+export function serializeCommand(parts) {
+    return parts.map(quoteCommandPart).join(" ");
+}
+export function quoteCommandPart(part) {
+    if (part.length === 0) {
+        return "\"\"";
+    }
+    if (!/[\s"'\\]/.test(part)) {
+        return part;
+    }
+    return `"${part.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/dist/src/core/countTokens.js

@@ -0,0 +1,8 @@
+export const tokenCountMethod = "estimated_chars_div_4";
+export function countTextChars(text) {
+    return text.length;
+}
+export function countEstimatedTokens(text) {
+    const chars = countTextChars(text);
+    return chars === 0 ? 0 : Math.ceil(chars / 4);
+}

package/dist/src/core/fileGlobs.js

@@ -0,0 +1,100 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { relativeWithinRoot, resolveWithinRoot } from "./pathSafety.js";
+const excludedDirNames = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    ".git",
+    "lab-output",
+    ".my-dev-kit",
+    ".my-dev-kit-v1",
+    ".my-dev-kit-lab",
+    "__pycache__"
+]);
+function isTempFile(relPath) {
+    return (relPath.endsWith(".tmp") ||
+        relPath.endsWith(".temp") ||
+        relPath.endsWith(".log") ||
+        relPath.endsWith(".pyc") ||
+        relPath.endsWith("~"));
+}
+function walkFiles(dir, root) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relPath = relativeWithinRoot(root, fullPath);
+        if (entry.isDirectory()) {
+            if (excludedDirNames.has(entry.name)) {
+                continue;
+            }
+            files.push(...walkFiles(fullPath, root));
+            continue;
+        }
+        if (!isTempFile(relPath)) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function baseDirectoryFromGlob(globPattern) {
+    const normalized = globPattern.replace(/\\/g, "/");
+    const wildcardIndex = normalized.search(/[*?]/);
+    if (wildcardIndex === -1) {
+        return normalized;
+    }
+    const prefix = normalized.slice(0, wildcardIndex);
+    const trimmed = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+    return trimmed || ".";
+}
+function matchesGlob(relPath, globPattern) {
+    const normalizedPath = relPath.replace(/\\/g, "/");
+    const normalizedGlob = globPattern.replace(/\\/g, "/");
+    if (normalizedGlob === "**/*") {
+        return true;
+    }
+    const baseDir = baseDirectoryFromGlob(normalizedGlob);
+    if (normalizedGlob.endsWith("/**/*")) {
+        const prefix = baseDir === "." ? "" : `${baseDir}/`;
+        return normalizedPath.startsWith(prefix);
+    }
+    if (normalizedGlob.includes("*")) {
+        const placeholder = "__DOUBLE_STAR__";
+        const escaped = normalizedGlob
+            .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+            .replace(/\*\*/g, placeholder)
+            .replace(/\*/g, "[^/]*")
+            .replaceAll(placeholder, ".*");
+        return new RegExp(`^${escaped}$`).test(normalizedPath);
+    }
+    return normalizedPath === normalizedGlob;
+}
+export function collectFilesForGlobs(targetRoot, globs) {
+    const resolvedRoot = path.resolve(targetRoot);
+    const fileMap = new Map();
+    for (const globPattern of globs) {
+        if (!globPattern || typeof globPattern !== "string") {
+            throw new Error("Invalid glob pattern.");
+        }
+        const baseDir = resolveWithinRoot(resolvedRoot, baseDirectoryFromGlob(globPattern));
+        let baseStats;
+        try {
+            baseStats = statSync(baseDir);
+        }
+        catch {
+            throw new Error(`Glob base directory does not exist: ${globPattern}`);
+        }
+        const candidateFiles = baseStats.isDirectory() ? walkFiles(baseDir, resolvedRoot) : [baseDir];
+        for (const candidate of candidateFiles) {
+            const relPath = relativeWithinRoot(resolvedRoot, candidate);
+            if (matchesGlob(relPath, globPattern)) {
+                fileMap.set(relPath, candidate);
+            }
+        }
+    }
+    return [...fileMap.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([relativePath, absolutePath]) => ({ relativePath, absolutePath }));
+}

package/dist/src/core/localProjectTarget.js

@@ -0,0 +1,75 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export function resolveLocalProjectTarget(targetPathArg, toolRoot) {
+    let targetRoot;
+    if (!targetPathArg) {
+        targetRoot = toolRoot;
+    }
+    else {
+        targetRoot = path.isAbsolute(targetPathArg)
+            ? targetPathArg
+            : path.resolve(process.cwd(), targetPathArg);
+        if (!fs.existsSync(targetRoot)) {
+            throw new Error(`Target path does not exist: ${targetRoot}`);
+        }
+        const stat = fs.statSync(targetRoot);
+        if (!stat.isDirectory()) {
+            throw new Error(`Target path is not a directory: ${targetRoot}`);
+        }
+    }
+    const resolvedTargetRoot = path.resolve(targetRoot);
+    const resolvedToolRoot = path.resolve(toolRoot);
+    const packageMetadata = readPackageMetadata(resolvedTargetRoot);
+    return {
+        targetRoot: resolvedTargetRoot,
+        toolRoot: resolvedToolRoot,
+        packageName: packageMetadata.packageName,
+        packageVersion: packageMetadata.packageVersion,
+        hasPackageJson: packageMetadata.hasPackageJson,
+        hasLockfile: hasLockfile(resolvedTargetRoot),
+        ...readGitMetadata(resolvedTargetRoot),
+        isSelf: resolvedTargetRoot === resolvedToolRoot,
+    };
+}
+function readPackageMetadata(targetRoot) {
+    try {
+        const pkgRaw = fs.readFileSync(path.join(targetRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(pkgRaw);
+        return {
+            hasPackageJson: true,
+            packageName: typeof pkg.name === "string" ? pkg.name : null,
+            packageVersion: typeof pkg.version === "string" ? pkg.version : null,
+        };
+    }
+    catch {
+        return {
+            hasPackageJson: false,
+            packageName: null,
+            packageVersion: null,
+        };
+    }
+}
+function hasLockfile(targetRoot) {
+    return (fs.existsSync(path.join(targetRoot, "package-lock.json")) ||
+        fs.existsSync(path.join(targetRoot, "yarn.lock")) ||
+        fs.existsSync(path.join(targetRoot, "pnpm-lock.yaml")));
+}
+function readGitMetadata(targetRoot) {
+    try {
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+            cwd: targetRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        const commit = execSync("git rev-parse --short HEAD", {
+            cwd: targetRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        return { branch, commit, hasGit: true };
+    }
+    catch {
+        return { branch: null, commit: null, hasGit: false };
+    }
+}

package/dist/src/core/pathSafety.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+export function resolveWithinRoot(root, relativeOrAbsolutePath) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedPath = path.resolve(resolvedRoot, relativeOrAbsolutePath);
+    const relative = path.relative(resolvedRoot, resolvedPath);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`Resolved path escapes target root: ${relativeOrAbsolutePath}`);
+    }
+    return resolvedPath;
+}
+export function relativeWithinRoot(root, filePath) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedFile = path.resolve(filePath);
+    const relative = path.relative(resolvedRoot, resolvedFile);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error(`File path escapes target root: ${filePath}`);
+    }
+    return relative.replace(/\\/g, "/");
+}

package/dist/src/core/pythonCommand.js

@@ -0,0 +1,30 @@
+import { spawnSync } from "node:child_process";
+const WINDOWS_PYTHON_CANDIDATES = [
+    { command: "py", argsPrefix: ["-3"] },
+    { command: "python", argsPrefix: [] }
+];
+const POSIX_PYTHON_CANDIDATES = [
+    { command: "python3", argsPrefix: [] },
+    { command: "python", argsPrefix: [] }
+];
+export function resolvePythonCommand(options = {}) {
+    const candidates = (options.platform ?? process.platform) === "win32"
+        ? WINDOWS_PYTHON_CANDIDATES
+        : POSIX_PYTHON_CANDIDATES;
+    const probe = options.probeAvailability ?? ((candidate) => canRunPython(candidate, options.timeoutMs ?? 5_000));
+    for (const candidate of candidates) {
+        if (probe(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}
+function canRunPython(candidate, timeoutMs) {
+    const result = spawnSync(candidate.command, [...candidate.argsPrefix, "--version"], {
+        encoding: "utf8",
+        shell: false,
+        timeout: timeoutMs,
+        windowsHide: true
+    });
+    return !result.error && result.status === 0;
+}

package/dist/src/core/resolveCommand.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+const windowsExtensionPreference = [".cmd", ".exe", ".bat", ".ps1", ""];
+export function resolveCommand(command, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    if (platform !== "win32") {
+        return {
+            originalCommand: command,
+            command,
+            argsPrefix: [],
+            resolutionKind: "direct",
+            resolvedPath: command,
+            warnings: []
+        };
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const candidate = findWindowsCommandCandidate(command, env, cwd);
+    if (!candidate) {
+        return {
+            originalCommand: command,
+            command,
+            argsPrefix: [],
+            resolutionKind: "unavailable",
+            warnings: [`Command was not found on PATH: ${command}`]
+        };
+    }
+    return commandForWindowsCandidate(command, candidate, env, options.allowPowerShellShim ?? true);
+}
+function commandForWindowsCandidate(originalCommand, resolvedPath, env, allowPowerShellShim) {
+    const extension = path.extname(resolvedPath).toLowerCase();
+    if (extension === ".ps1") {
+        if (!allowPowerShellShim) {
+            return {
+                originalCommand,
+                command: resolvedPath,
+                argsPrefix: [],
+                resolutionKind: "unavailable",
+                resolvedPath,
+                warnings: [`PowerShell shim execution is disabled for command: ${resolvedPath}`]
+            };
+        }
+        return {
+            originalCommand,
+            command: "powershell.exe",
+            argsPrefix: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolvedPath],
+            resolutionKind: "windows-powershell-shim",
+            resolvedPath,
+            warnings: []
+        };
+    }
+    if (extension === ".cmd" || extension === ".bat") {
+        return {
+            originalCommand,
+            command: env.ComSpec ?? env.COMSPEC ?? process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe",
+            argsPrefix: ["/d", "/s", "/c", "call"],
+            resolutionKind: "windows-cmd-shim",
+            resolvedPath,
+            warnings: []
+        };
+    }
+    return {
+        originalCommand,
+        command: resolvedPath,
+        argsPrefix: [],
+        resolutionKind: path.extname(originalCommand) ? "direct" : "path-extension",
+        resolvedPath,
+        warnings: []
+    };
+}
+function findWindowsCommandCandidate(command, env, cwd) {
+    if (hasPathSeparator(command) || path.isAbsolute(command)) {
+        return findCandidateInDirectory(path.resolve(cwd, command));
+    }
+    for (const searchDir of getPathEntries(env)) {
+        const candidate = findCandidateInDirectory(path.join(searchDir, command));
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function findCandidateInDirectory(basePath) {
+    const extension = path.extname(basePath);
+    if (extension) {
+        return isExecutableFile(basePath) ? basePath : undefined;
+    }
+    for (const candidateExtension of windowsExtensionPreference) {
+        const candidatePath = `${basePath}${candidateExtension}`;
+        if (isExecutableFile(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return undefined;
+}
+function getPathEntries(env) {
+    const pathValue = env.Path ?? env.PATH ?? "";
+    return pathValue.split(path.delimiter).filter(Boolean);
+}
+function hasPathSeparator(command) {
+    return command.includes("/") || command.includes("\\");
+}
+function isExecutableFile(candidatePath) {
+    try {
+        return fs.statSync(candidatePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/core/runMeasuredCommand.js

@@ -0,0 +1,143 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseCommandString } from "./commandLine.js";
+import { resolveCommand } from "./resolveCommand.js";
+export { parseCommandString } from "./commandLine.js";
+export async function runMeasuredCommand(options) {
+    await mkdir(options.outDir, { recursive: true });
+    const parsed = parseCommandString(options.commandString);
+    const resolution = options.resolveCommand === false
+        ? {
+            originalCommand: parsed.executable,
+            command: parsed.executable,
+            argsPrefix: [],
+            resolutionKind: "direct",
+            resolvedPath: parsed.executable,
+            warnings: []
+        }
+        : resolveCommand(parsed.executable, {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env },
+            allowPowerShellShim: options.allowPowerShellShim
+        });
+    const executable = resolution.command;
+    const trailingArgs = [...parsed.args, ...(options.extraArgs ?? [])];
+    const args = resolution.resolutionKind === "windows-cmd-shim" && resolution.resolvedPath
+        ? [...resolution.argsPrefix, resolution.resolvedPath, ...trailingArgs]
+        : [...resolution.argsPrefix, ...trailingArgs];
+    const stdoutPath = path.join(options.outDir, `${options.commandId}.stdout.txt`);
+    const stderrPath = path.join(options.outDir, `${options.commandId}.stderr.txt`);
+    const telemetryPath = path.join(options.outDir, `${options.commandId}.telemetry.json`);
+    const startedAt = new Date().toISOString();
+    const started = Date.now();
+    const result = await new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let spawnError;
+        let timedOut = false;
+        let timeout;
+        let child;
+        try {
+            child = spawn(executable, args, {
+                cwd: options.cwd,
+                env: { ...process.env, ...options.env },
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"]
+            });
+        }
+        catch (error) {
+            const endedAt = new Date().toISOString();
+            const durationMs = Date.now() - started;
+            const message = error instanceof Error ? error.message : String(error);
+            const measured = {
+                commandId: options.commandId,
+                commandString: options.commandString,
+                executable,
+                args,
+                cwd: options.cwd,
+                startedAt,
+                endedAt,
+                durationMs,
+                exitCode: null,
+                stdout,
+                stderr,
+                stdoutPath,
+                stderrPath,
+                telemetryPath,
+                ok: false,
+                error: message,
+                resolvedCommand: resolution
+            };
+            void Promise.all([
+                writeFile(stdoutPath, stdout, "utf8"),
+                writeFile(stderrPath, stderr, "utf8"),
+                writeFile(telemetryPath, JSON.stringify(measured, null, 2), "utf8")
+            ]).then(() => resolve(measured));
+            return;
+        }
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (error) => {
+            spawnError = error.message;
+        });
+        if (options.timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                spawnError = `Command timed out after ${options.timeoutMs}ms.`;
+                killProcessTree(child.pid);
+            }, options.timeoutMs);
+        }
+        child.on("close", async (exitCode) => {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            const endedAt = new Date().toISOString();
+            const durationMs = Date.now() - started;
+            await writeFile(stdoutPath, stdout, "utf8");
+            await writeFile(stderrPath, stderr, "utf8");
+            const measured = {
+                commandId: options.commandId,
+                commandString: options.commandString,
+                executable,
+                args,
+                cwd: options.cwd,
+                startedAt,
+                endedAt,
+                durationMs,
+                exitCode,
+                stdout,
+                stderr,
+                stdoutPath,
+                stderrPath,
+                telemetryPath,
+                ok: exitCode === 0 && !spawnError && !timedOut,
+                error: spawnError,
+                resolvedCommand: resolution
+            };
+            await writeFile(telemetryPath, JSON.stringify(measured, null, 2), "utf8");
+            resolve(measured);
+        });
+    });
+    return result;
+}
+function killProcessTree(pid) {
+    if (!pid) {
+        return;
+    }
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { shell: false, stdio: "ignore" });
+        killer.on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // The child may have exited between timeout scheduling and kill.
+    }
+}