@stigmer/runner 3.0.1

package/src/shared/workspace/__tests__/platform-mount.test.ts

@@ -0,0 +1,378 @@
+import { describe, it, expect } from "vitest";
+import {
+  PLATFORM_PREFIX,
+  PLATFORM_DIR_NAME,
+  STIGMER_PLATFORM_DIR_ENV,
+  classifyPlatformPath,
+  humanizePlatformRefs,
+  resolvePlatformCommand,
+  humanizeSandboxPaths,
+  resolveDisplayEnvVars,
+} from "../platform-mount.js";
+
+// ── Constants ────────────────────────────────────────────────────────────
+
+describe("constants", () => {
+  it("PLATFORM_PREFIX ends with /", () => {
+    expect(PLATFORM_PREFIX).toBe(".stigmer/");
+  });
+
+  it("PLATFORM_DIR_NAME has no slash", () => {
+    expect(PLATFORM_DIR_NAME).toBe(".stigmer");
+  });
+
+  it("STIGMER_PLATFORM_DIR_ENV is the canonical env var name", () => {
+    expect(STIGMER_PLATFORM_DIR_ENV).toBe("STIGMER_PLATFORM_DIR");
+  });
+});
+
+// ── classifyPlatformPath ─────────────────────────────────────────────────
+
+describe("classifyPlatformPath", () => {
+  it.each([
+    [".stigmer/skills/a/SKILL.md", true, "skills/a/SKILL.md"],
+    ["/.stigmer/inputs/data.pdf", true, "inputs/data.pdf"],
+    [".stigmer", true, ""],
+    [".stigmer/", true, ""],
+    ["src/main.py", false, "src/main.py"],
+    ["/bin/tools", false, "bin/tools"],
+    ["", false, ""],
+    [".", false, "."],
+    [".stigmerx/stuff", false, ".stigmerx/stuff"],
+    ["a/.stigmer/b", false, "a/.stigmer/b"],
+  ])("classifies %j → isPlatform=%s remainder=%j", (path, expectedPlatform, expectedRemainder) => {
+    const result = classifyPlatformPath(path);
+    expect(result.isPlatform).toBe(expectedPlatform);
+    expect(result.remainder).toBe(expectedRemainder);
+  });
+
+  it("strips multiple leading slashes", () => {
+    const result = classifyPlatformPath("///.stigmer/skills/x");
+    expect(result.isPlatform).toBe(true);
+    expect(result.remainder).toBe("skills/x");
+  });
+
+  it("handles nested platform paths", () => {
+    const result = classifyPlatformPath(".stigmer/skills/deep/nested/file.md");
+    expect(result.isPlatform).toBe(true);
+    expect(result.remainder).toBe("skills/deep/nested/file.md");
+  });
+
+  it("does not match .stigmer embedded in a deeper path", () => {
+    const result = classifyPlatformPath("src/.stigmer/foo");
+    expect(result.isPlatform).toBe(false);
+    expect(result.remainder).toBe("src/.stigmer/foo");
+  });
+});
+
+// ── humanizePlatformRefs ─────────────────────────────────────────────────
+
+describe("humanizePlatformRefs", () => {
+  it("replaces $STIGMER_PLATFORM_DIR with path", () => {
+    expect(
+      humanizePlatformRefs("python3 $STIGMER_PLATFORM_DIR/skills/s/run.py"),
+    ).toBe("python3 .stigmer/skills/s/run.py");
+  });
+
+  it("replaces ${STIGMER_PLATFORM_DIR} with path", () => {
+    expect(
+      humanizePlatformRefs("python3 ${STIGMER_PLATFORM_DIR}/skills/s/run.py"),
+    ).toBe("python3 .stigmer/skills/s/run.py");
+  });
+
+  it("replaces standalone $STIGMER_PLATFORM_DIR", () => {
+    expect(humanizePlatformRefs("echo $STIGMER_PLATFORM_DIR")).toBe(
+      "echo .stigmer",
+    );
+  });
+
+  it("replaces standalone ${STIGMER_PLATFORM_DIR}", () => {
+    expect(humanizePlatformRefs("echo ${STIGMER_PLATFORM_DIR}")).toBe(
+      "echo .stigmer",
+    );
+  });
+
+  it("passes through text without env var", () => {
+    expect(humanizePlatformRefs("ls -la")).toBe("ls -la");
+  });
+
+  it("returns empty string unchanged", () => {
+    expect(humanizePlatformRefs("")).toBe("");
+  });
+
+  it("handles multiple occurrences", () => {
+    expect(
+      humanizePlatformRefs(
+        "cp $STIGMER_PLATFORM_DIR/a.txt ${STIGMER_PLATFORM_DIR}/b.txt",
+      ),
+    ).toBe("cp .stigmer/a.txt .stigmer/b.txt");
+  });
+
+  it("replaces mid-string occurrence", () => {
+    expect(
+      humanizePlatformRefs(
+        "Execute command: python3 $STIGMER_PLATFORM_DIR/skills/skill-creator/scripts/init_skill.py agent-creator --path .",
+      ),
+    ).toBe(
+      "Execute command: python3 .stigmer/skills/skill-creator/scripts/init_skill.py agent-creator --path .",
+    );
+  });
+
+  it("does not match partial name $STIGMER_PLATFORM_DIR_EXTRA", () => {
+    const text = "echo $STIGMER_PLATFORM_DIR_EXTRA";
+    expect(humanizePlatformRefs(text)).toBe(text);
+  });
+
+  it("does not match $STIGMER_PLATFORM_DIRECTORY", () => {
+    const text = "echo $STIGMER_PLATFORM_DIRECTORY";
+    expect(humanizePlatformRefs(text)).toBe(text);
+  });
+});
+
+// ── resolvePlatformCommand ───────────────────────────────────────────────
+
+describe("resolvePlatformCommand", () => {
+  it("replaces .stigmer in a command with $STIGMER_PLATFORM_DIR", () => {
+    expect(
+      resolvePlatformCommand("python3 .stigmer/skills/s/run.py"),
+    ).toBe("python3 $STIGMER_PLATFORM_DIR/skills/s/run.py");
+  });
+
+  it("replaces standalone .stigmer", () => {
+    expect(resolvePlatformCommand("ls .stigmer")).toBe(
+      "ls $STIGMER_PLATFORM_DIR",
+    );
+  });
+
+  it("does not replace .stigmer inside a path (foo/.stigmer/bar)", () => {
+    expect(resolvePlatformCommand("echo foo/.stigmer/bar")).toBe(
+      "echo foo/.stigmer/bar",
+    );
+  });
+
+  it("does not replace .stigmer inside a word (my.stigmer)", () => {
+    expect(resolvePlatformCommand("echo my.stigmer")).toBe(
+      "echo my.stigmer",
+    );
+  });
+
+  it("passes through text without .stigmer", () => {
+    expect(resolvePlatformCommand("ls -la")).toBe("ls -la");
+  });
+
+  it("returns empty string unchanged", () => {
+    expect(resolvePlatformCommand("")).toBe("");
+  });
+
+  it("handles multiple standalone occurrences", () => {
+    expect(
+      resolvePlatformCommand("ls .stigmer && cat .stigmer/skills/a.md"),
+    ).toBe(
+      "ls $STIGMER_PLATFORM_DIR && cat $STIGMER_PLATFORM_DIR/skills/a.md",
+    );
+  });
+
+  it("is the inverse of humanizePlatformRefs for display→command roundtrip", () => {
+    const display = "python3 .stigmer/skills/s/run.py";
+    const command = resolvePlatformCommand(display);
+    expect(command).toBe("python3 $STIGMER_PLATFORM_DIR/skills/s/run.py");
+    expect(humanizePlatformRefs(command)).toBe(display);
+  });
+});
+
+// ── humanizeSandboxPaths ─────────────────────────────────────────────────
+
+describe("humanizeSandboxPaths", () => {
+  const wsRoot = "/home/daytona/workspace";
+
+  it("strips workspace root prefix from paths", () => {
+    expect(
+      humanizeSandboxPaths("ls /home/daytona/workspace/plantonhq/", wsRoot),
+    ).toBe("ls plantonhq/");
+  });
+
+  it("replaces bare workspace root with '.'", () => {
+    expect(
+      humanizeSandboxPaths("cd /home/daytona/workspace && ls", wsRoot),
+    ).toBe("cd . && ls");
+  });
+
+  it("replaces sandbox home with '~'", () => {
+    expect(
+      humanizeSandboxPaths("cat /home/daytona/.bashrc", wsRoot),
+    ).toBe("cat ~/.bashrc");
+  });
+
+  it("passes through text without sandbox paths", () => {
+    expect(humanizeSandboxPaths("ls -la", wsRoot)).toBe("ls -la");
+  });
+
+  it("returns text unchanged when workspaceRoot is empty", () => {
+    expect(humanizeSandboxPaths("anything", "")).toBe("anything");
+  });
+
+  it("returns empty string unchanged", () => {
+    expect(humanizeSandboxPaths("", wsRoot)).toBe("");
+  });
+
+  it("handles trailing slash on workspace root", () => {
+    expect(
+      humanizeSandboxPaths("ls /home/daytona/workspace/src/", wsRoot + "/"),
+    ).toBe("ls src/");
+  });
+
+  it("handles multiple path replacements in one string", () => {
+    expect(
+      humanizeSandboxPaths(
+        "diff /home/daytona/workspace/a.ts /home/daytona/workspace/b.ts",
+        wsRoot,
+      ),
+    ).toBe("diff a.ts b.ts");
+  });
+
+  it("replaces workspace root even when embedded in longer path", () => {
+    // Simple string replacement (matches Python behavior) — workspace2
+    // becomes .2 because the replacement is not word-boundary-aware.
+    expect(
+      humanizeSandboxPaths("echo /home/daytona/workspace2/foo", wsRoot),
+    ).toBe("echo .2/foo");
+  });
+
+  it("replaces home directory for paths outside workspace", () => {
+    expect(
+      humanizeSandboxPaths("cat /home/daytona/.git-credentials", wsRoot),
+    ).toBe("cat ~/.git-credentials");
+  });
+
+  it("handles workspace root at filesystem root level", () => {
+    expect(
+      humanizeSandboxPaths("ls /workspace/foo", "/workspace"),
+    ).toBe("ls foo");
+  });
+});
+
+// ── resolveDisplayEnvVars ────────────────────────────────────────────────
+
+describe("resolveDisplayEnvVars", () => {
+  it("resolves $KEY to value", () => {
+    expect(
+      resolveDisplayEnvVars("--path $OUTPUT_DIR", { OUTPUT_DIR: "." }),
+    ).toBe("--path .");
+  });
+
+  it("resolves ${KEY} to value", () => {
+    expect(
+      resolveDisplayEnvVars("--path ${OUTPUT_DIR}", { OUTPUT_DIR: "out" }),
+    ).toBe("--path out");
+  });
+
+  it("resolves multiple variables", () => {
+    expect(
+      resolveDisplayEnvVars("$OUTPUT_DIR/$PROJECT_NAME", {
+        OUTPUT_DIR: "build",
+        PROJECT_NAME: "demo",
+      }),
+    ).toBe("build/demo");
+  });
+
+  it("returns text unchanged when envVars is empty", () => {
+    expect(resolveDisplayEnvVars("$OUTPUT_DIR", {})).toBe("$OUTPUT_DIR");
+  });
+
+  it("returns empty string unchanged", () => {
+    expect(resolveDisplayEnvVars("", { OUTPUT_DIR: "." })).toBe("");
+  });
+
+  it("does not resolve secret keys", () => {
+    expect(
+      resolveDisplayEnvVars(
+        "echo $API_TOKEN",
+        { API_TOKEN: "sk-secret-xxx" },
+        new Set(["API_TOKEN"]),
+      ),
+    ).toBe("echo $API_TOKEN");
+  });
+
+  it("resolves non-secret keys even with sensitive-looking names", () => {
+    expect(
+      resolveDisplayEnvVars(
+        "echo $DB_PASSWORD",
+        { DB_PASSWORD: "hunter2" },
+        new Set(),
+      ),
+    ).toBe("echo hunter2");
+  });
+
+  it("handles mixed secret and non-secret keys", () => {
+    expect(
+      resolveDisplayEnvVars(
+        "$OUTPUT_DIR $AUTH_TOKEN",
+        { OUTPUT_DIR: ".", AUTH_TOKEN: "sk-xxx" },
+        new Set(["AUTH_TOKEN"]),
+      ),
+    ).toBe(". $AUTH_TOKEN");
+  });
+
+  it("skips $STIGMER_PLATFORM_DIR (handled by humanizePlatformRefs)", () => {
+    expect(
+      resolveDisplayEnvVars("$STIGMER_PLATFORM_DIR/skills", {
+        STIGMER_PLATFORM_DIR: "/tmp/platform",
+      }),
+    ).toBe("$STIGMER_PLATFORM_DIR/skills");
+  });
+
+  it("does not match partial variable names", () => {
+    expect(
+      resolveDisplayEnvVars("$OUTPUT_DIR_EXTRA", { OUTPUT_DIR: "." }),
+    ).toBe("$OUTPUT_DIR_EXTRA");
+  });
+
+  it("resolves all keys when no secretKeys provided", () => {
+    expect(
+      resolveDisplayEnvVars("$API_TOKEN", { API_TOKEN: "resolved" }),
+    ).toBe("resolved");
+  });
+
+  it("handles keys with special regex characters", () => {
+    expect(
+      resolveDisplayEnvVars("$MY_KEY", { "MY_KEY": "value" }),
+    ).toBe("value");
+  });
+
+  it("handles value at end of string (no trailing char after $KEY)", () => {
+    expect(
+      resolveDisplayEnvVars("path=$OUTPUT_DIR", { OUTPUT_DIR: "/out" }),
+    ).toBe("path=/out");
+  });
+});
+
+// ── Combined pipeline ────────────────────────────────────────────────────
+
+describe("combined display pipeline", () => {
+  it("humanize platform refs first, then resolve env vars", () => {
+    let text = "python3 $STIGMER_PLATFORM_DIR/run.py --path $OUTPUT_DIR";
+    text = humanizePlatformRefs(text);
+    text = resolveDisplayEnvVars(text, { OUTPUT_DIR: "." });
+    expect(text).toBe("python3 .stigmer/run.py --path .");
+  });
+
+  it("full pipeline: humanize platform → resolve env → humanize sandbox", () => {
+    const wsRoot = "/home/daytona/workspace";
+    let text =
+      "python3 $STIGMER_PLATFORM_DIR/run.py --cwd /home/daytona/workspace/src --out $OUTPUT_DIR";
+
+    text = humanizePlatformRefs(text);
+    text = resolveDisplayEnvVars(text, { OUTPUT_DIR: "build" });
+    text = humanizeSandboxPaths(text, wsRoot);
+
+    expect(text).toBe("python3 .stigmer/run.py --cwd src --out build");
+  });
+
+  it("command roundtrip: display → resolve → humanize", () => {
+    const display = "bash .stigmer/skills/lint/run.sh --fix";
+    const command = resolvePlatformCommand(display);
+    expect(command).toBe("bash $STIGMER_PLATFORM_DIR/skills/lint/run.sh --fix");
+    const backToDisplay = humanizePlatformRefs(command);
+    expect(backToDisplay).toBe(display);
+  });
+});

package/src/shared/workspace/__tests__/provisioner.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { WorkspaceProvisioner } from "../provisioner.js";
+import { SourceType, WorkspaceProvisionError } from "../types.js";
+import { LocalWorkspaceBackend } from "../local-backend.js";
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "ws-test-"));
+}
+
+describe("WorkspaceProvisioner", () => {
+  let provisioner: WorkspaceProvisioner;
+
+  beforeEach(() => {
+    provisioner = new WorkspaceProvisioner();
+  });
+
+  describe("empty workspace", () => {
+    it("returns EMPTY source type when no source is provided", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const result = await provisioner.provision(undefined, backend, {}, true);
+      expect(result.sourceType).toBe(SourceType.EMPTY);
+      expect(result.rootDir).toBe(root);
+      expect(result.consumedKeys).toEqual([]);
+    });
+
+    it("returns EMPTY when source case is undefined", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const result = await provisioner.provision(
+        { source: { case: undefined, value: undefined } },
+        backend, {}, true,
+      );
+      expect(result.sourceType).toBe(SourceType.EMPTY);
+    });
+  });
+
+  describe("local path", () => {
+    it("returns LOCAL_PATH with the original directory", async () => {
+      const root = makeTempDir();
+      const projectDir = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const result = await provisioner.provision(
+        { source: { case: "localPath", value: { path: projectDir } } },
+        backend, {}, true,
+      );
+      expect(result.sourceType).toBe(SourceType.LOCAL_PATH);
+      expect(result.rootDir).toBe(projectDir);
+    });
+
+    it("rejects relative paths", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      await expect(
+        provisioner.provision(
+          { source: { case: "localPath", value: { path: "relative/path" } } },
+          backend, {}, true,
+        ),
+      ).rejects.toThrow(WorkspaceProvisionError);
+    });
+
+    it("rejects in cloud mode", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      await expect(
+        provisioner.provision(
+          { source: { case: "localPath", value: { path: root } } },
+          backend, {}, false,
+        ),
+      ).rejects.toThrow("only supported in local mode");
+    });
+
+    it("rejects non-existent paths", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      await expect(
+        provisioner.provision(
+          { source: { case: "localPath", value: { path: "/nonexistent/path" } } },
+          backend, {}, true,
+        ),
+      ).rejects.toThrow("does not exist");
+    });
+  });
+
+  describe("provisionAll", () => {
+    it("returns empty array for no entries", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const results = await provisioner.provisionAll([], backend, {}, true);
+      expect(results).toEqual([]);
+    });
+
+    it("stamps entryName on each result", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const results = await provisioner.provisionAll(
+        [{ name: "app", source: undefined }],
+        backend, {}, true,
+      );
+      expect(results).toHaveLength(1);
+      expect(results[0].entryName).toBe("app");
+      expect(results[0].sourceType).toBe(SourceType.EMPTY);
+    });
+  });
+
+  describe("WORKSPACE_PROVISION_ key stripping", () => {
+    it("adds prefixed keys to consumedKeys", async () => {
+      const root = makeTempDir();
+      const backend = new LocalWorkspaceBackend(root);
+      const env = { WORKSPACE_PROVISION_TOKEN: "secret", OTHER: "value" };
+      const result = await provisioner.provision(undefined, backend, env, true);
+      expect(result.consumedKeys).toContain("WORKSPACE_PROVISION_TOKEN");
+      expect(result.consumedKeys).not.toContain("OTHER");
+    });
+  });
+});
+
+describe("LocalWorkspaceBackend", () => {
+  it("executes shell commands in the workspace root", async () => {
+    const root = makeTempDir();
+    writeFileSync(join(root, "test.txt"), "hello");
+    const backend = new LocalWorkspaceBackend(root);
+    const output = await backend.execute("cat test.txt");
+    expect(output).toBe("hello");
+  });
+
+  it("checks file existence", async () => {
+    const root = makeTempDir();
+    writeFileSync(join(root, "exists.txt"), "");
+    const backend = new LocalWorkspaceBackend(root);
+    expect(await backend.exists("exists.txt")).toBe(true);
+    expect(await backend.exists("nope.txt")).toBe(false);
+  });
+
+  it("reads and writes files", async () => {
+    const root = makeTempDir();
+    const backend = new LocalWorkspaceBackend(root);
+    await backend.writeFile("out.txt", "content");
+    const content = await backend.readFile("out.txt");
+    expect(content).toBe("content");
+  });
+});

package/src/shared/workspace/file-tree.ts

@@ -0,0 +1,116 @@
+/**
+ * Generates a concise workspace file tree for system prompts.
+ *
+ * Produces a markdown-formatted directory listing that helps the agent
+ * understand the project structure. Respects .gitignore when present
+ * and caps depth to keep the system prompt manageable.
+ */
+
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import { join, relative, basename } from "node:path";
+
+const MAX_DEPTH = 4;
+const MAX_ENTRIES = 200;
+
+const DEFAULT_IGNORES = new Set([
+  "node_modules",
+  ".git",
+  "__pycache__",
+  ".venv",
+  ".mypy_cache",
+  ".ruff_cache",
+  ".pytest_cache",
+  "dist",
+  "build",
+  ".next",
+  ".stigmer",
+  ".cursor",
+]);
+
+export interface FileTreeOptions {
+  headingLevel?: number;
+  maxDepth?: number;
+  maxEntries?: number;
+}
+
+export function buildWorkspaceFileTree(
+  rootDir: string,
+  options?: FileTreeOptions,
+): string | null {
+  const headingLevel = options?.headingLevel ?? 3;
+  const maxDepth = options?.maxDepth ?? MAX_DEPTH;
+  const maxEntries = options?.maxEntries ?? MAX_ENTRIES;
+
+  const gitignorePatterns = loadGitignore(rootDir);
+  const lines: string[] = [];
+  let count = 0;
+
+  function walk(dir: string, depth: number, prefix: string): boolean {
+    if (depth > maxDepth) return false;
+
+    let entries: string[];
+    try {
+      entries = readdirSync(dir).sort();
+    } catch {
+      return false;
+    }
+
+    for (const entry of entries) {
+      if (count >= maxEntries) return true;
+      if (DEFAULT_IGNORES.has(entry)) continue;
+      if (entry.startsWith(".") && entry !== ".env.example") continue;
+
+      const fullPath = join(dir, entry);
+      const rel = relative(rootDir, fullPath);
+
+      if (isGitignored(rel, gitignorePatterns)) continue;
+
+      let isDir = false;
+      try {
+        isDir = statSync(fullPath).isDirectory();
+      } catch {
+        continue;
+      }
+
+      lines.push(`${prefix}${isDir ? `${entry}/` : entry}`);
+      count++;
+
+      if (isDir) {
+        const truncated = walk(fullPath, depth + 1, prefix + "  ");
+        if (truncated) return true;
+      }
+    }
+    return false;
+  }
+
+  const truncated = walk(rootDir, 0, "");
+
+  if (lines.length === 0) return null;
+
+  const heading = "#".repeat(headingLevel);
+  const tree = lines.join("\n");
+  const suffix = truncated ? "\n  ... (truncated)" : "";
+
+  return `${heading} Project Structure\n\n\`\`\`\n${tree}${suffix}\n\`\`\``;
+}
+
+function loadGitignore(rootDir: string): string[] {
+  try {
+    const content = readFileSync(join(rootDir, ".gitignore"), "utf-8");
+    return content
+      .split("\n")
+      .map(l => l.trim())
+      .filter(l => l && !l.startsWith("#"));
+  } catch {
+    return [];
+  }
+}
+
+function isGitignored(relativePath: string, patterns: string[]): boolean {
+  const name = basename(relativePath);
+  for (const pattern of patterns) {
+    if (pattern.endsWith("/") && name === pattern.slice(0, -1)) return true;
+    if (name === pattern) return true;
+  }
+  return false;
+}