@wrongstack/tools 0.313.0 → 0.316.1

package/dist/chunk-EJWSCQ6D.js

@@ -0,0 +1,137 @@
+import {
+  tryLegacyCodeOperation
+} from "./chunk-PQKK5JH7.js";
+import {
+  spawnStream
+} from "./chunk-22B7GE5T.js";
+import {
+  detectPackageManager,
+  normalizeCommandOutput,
+  safeResolveReal
+} from "./chunk-D33S4RQG.js";
+
+// src/typecheck.ts
+import * as path from "node:path";
+var typecheckTool = {
+  name: "typecheck",
+  category: "Code Quality",
+  description: "Run the project's TypeScript type checker (`tsc --noEmit` or equivalent). Essential for verifying type safety before making changes or committing.",
+  usageHint: "ALWAYS RUN BEFORE CONSIDERING WORK COMPLETE:\n\n- Use this to catch type errors early.\n- In monorepos, `all: true` will check every package.\n- This is one of the most important quality gates in this project.\nNever claim a task is done without a clean typecheck (unless the user explicitly says otherwise).",
+  permission: "confirm",
+  mutating: false,
+  timeoutMs: 12e4,
+  capabilities: ["shell.restricted"],
+  icon: "code",
+  inputSchema: {
+    type: "object",
+    properties: {
+      project: { type: "string", description: "Path to tsconfig.json (default: auto-detect)" },
+      cwd: { type: "string", description: "Working directory (default: cwd)" },
+      strict: {
+        type: "boolean",
+        description: "Add --strict flag for maximum type checking (default: false)"
+      },
+      all: {
+        type: "boolean",
+        description: "Type-check all workspace packages (pnpm workspaces run `pnpm -r exec tsc --noEmit`; other setups run a single `tsc --noEmit` at cwd) (default: false)"
+      }
+    }
+  },
+  async execute(input, ctx, opts) {
+    let final;
+    const executeStream = typecheckTool.executeStream;
+    if (!executeStream) throw new Error("typecheckTool: stream execution unavailable");
+    for await (const ev of executeStream(input, ctx, opts)) {
+      if (ev.type === "final") final = ev.output;
+    }
+    if (!final) throw new Error("typecheck: stream ended without final event");
+    return final;
+  },
+  async *executeStream(input, ctx, opts) {
+    const cwd = input.cwd ? await safeResolveReal(input.cwd, ctx) : ctx.cwd;
+    const bridge = await tryLegacyCodeOperation("semantic", {
+      cwd,
+      projectRoot: ctx.projectRoot,
+      signal: opts.signal
+    });
+    if (bridge?.run) {
+      const run = bridge.run;
+      yield {
+        type: "final",
+        output: {
+          project: `${bridge.language} workspace`,
+          exit_code: run.exitCode ?? 0,
+          errors: run.summary.errors,
+          warnings: run.summary.warnings,
+          output: normalizeCommandOutput(run.output || run.error || ""),
+          truncated: run.truncated
+        }
+      };
+      return;
+    }
+    let cmd;
+    let cmdArgs;
+    let project;
+    if (input.all) {
+      project = "workspace";
+      const tscArgs = ["--noEmit"];
+      if (input.strict) tscArgs.push("--strict");
+      const manager = await detectPackageManager(cwd, ctx.projectRoot);
+      if (manager === "pnpm") {
+        cmd = "pnpm";
+        cmdArgs = ["-r", "--no-bail", "exec", "tsc", ...tscArgs];
+      } else {
+        cmd = "npx";
+        cmdArgs = ["tsc", ...tscArgs];
+      }
+    } else {
+      const tsconfig = input.project ? await safeResolveReal(input.project, ctx) : await findTsConfig(cwd);
+      const tscArgs = ["--noEmit"];
+      if (input.strict) tscArgs.push("--strict");
+      if (tsconfig) tscArgs.push("--project", tsconfig);
+      project = tsconfig ?? "default";
+      cmd = "npx";
+      cmdArgs = ["tsc", ...tscArgs];
+    }
+    yield { type: "log", text: `${cmd} ${cmdArgs.join(" ")}`, data: { project } };
+    const result = yield* spawnStream({
+      cmd,
+      args: cmdArgs,
+      cwd,
+      signal: opts.signal,
+      maxBytes: 2e5
+    });
+    const combined = `${result.stdout}
+${result.stderr}`;
+    const errors = [...combined.matchAll(/^.*\berror TS\d+:/gm)].length;
+    const warnings = [...combined.matchAll(/^.*\bwarning TS\d+:/gm)].length;
+    yield {
+      type: "final",
+      output: {
+        project,
+        exit_code: result.exitCode,
+        errors,
+        warnings,
+        output: normalizeCommandOutput(result.stdout || result.stderr || result.error || ""),
+        truncated: result.truncated
+      }
+    };
+  }
+};
+async function findTsConfig(cwd) {
+  const { stat } = await import("node:fs/promises");
+  const candidates = ["tsconfig.json", "tsconfig.base.json"];
+  for (const f of candidates) {
+    try {
+      const s = await stat(path.join(cwd, f));
+      if (s.isFile()) return path.join(cwd, f);
+    } catch {
+    }
+  }
+  return null;
+}
+
+export {
+  typecheckTool
+};
+//# sourceMappingURL=chunk-EJWSCQ6D.js.map

package/dist/chunk-EMRGN4KM.js

@@ -0,0 +1,170 @@
+import {
+  ensureInsideRoot,
+  safeResolveReal
+} from "./chunk-D33S4RQG.js";
+
+// src/document.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+var documentTool = {
+  name: "document",
+  category: "Project",
+  description: "DEPRECATED \u2014 read-only preview stub that lists undocumented symbols as `skipped` candidates. It never writes files and does not generate real docstrings. If the auto-doc plugin is enabled, use its `auto_doc` tool (with `dry_run: true` to preview) instead.",
+  usageHint: "Deprecated: this tool only lists undocumented symbols with placeholder comments \u2014 it does not generate real JSDoc/TSDoc and writes nothing. When the auto-doc plugin is enabled, prefer its `auto_doc` tool (`dry_run: true` for previewing, without it for writing).",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 3e4,
+  capabilities: ["fs.read"],
+  icon: "document",
+  inputSchema: {
+    type: "object",
+    properties: {
+      target: {
+        type: "string",
+        enum: ["file", "function", "class", "type", "all"],
+        description: "What to document"
+      },
+      path: {
+        type: "string",
+        description: "Specific file path to document"
+      },
+      files: {
+        type: "string",
+        description: "File(s) to process: single path, comma-separated list, or glob"
+      },
+      style: {
+        type: "string",
+        enum: ["jsdoc", "tsdoc", "block"],
+        description: "Documentation style (default: jsdoc)"
+      },
+      cwd: { type: "string", description: "Working directory (default: cwd)" }
+    }
+  },
+  async execute(input, ctx) {
+    const cwd = input.cwd ? await safeResolveReal(input.cwd, ctx) : ctx.cwd;
+    const style = input.style ?? "jsdoc";
+    const results = [];
+    let filesProcessed = 0;
+    let itemsDocumented = 0;
+    const fileList = input.files ? await resolveFiles(
+      Array.isArray(input.files) ? input.files.join(",") : input.files,
+      cwd,
+      ctx
+    ) : input.path ? [await safeResolveReal(input.path, ctx)] : [];
+    for (const absPath of fileList) {
+      try {
+        const content = await fs.readFile(absPath, "utf8");
+        filesProcessed++;
+        const processed = processFile(
+          content,
+          absPath,
+          style,
+          input.overwrite ?? false,
+          input.target ?? "all"
+        );
+        results.push(...processed);
+        itemsDocumented += processed.filter((r) => r.status === "documented").length;
+      } catch (e) {
+        results.push({
+          path: absPath,
+          name: absPath.split("/").pop() ?? absPath,
+          signature: "",
+          docstring: "",
+          status: "error",
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+    return {
+      files_processed: filesProcessed,
+      items_documented: itemsDocumented,
+      results,
+      style
+    };
+  }
+};
+async function resolveFiles(filesInput, cwd, ctx) {
+  const files = filesInput.split(",");
+  const resolved = [];
+  for (const f of files) {
+    const entry = f.trim();
+    if (!entry) continue;
+    let absPath;
+    try {
+      absPath = ensureInsideRoot(path.resolve(cwd, entry), ctx);
+    } catch {
+      continue;
+    }
+    try {
+      const stat2 = await fs.stat(absPath);
+      if (stat2.isFile()) resolved.push(absPath);
+    } catch {
+    }
+  }
+  return resolved;
+}
+function processFile(content, absPath, _style, _overwrite, target) {
+  const results = [];
+  const functionRegex = /(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
+  const arrowRegex = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/g;
+  const classRegex = /class\s+(\w+)/g;
+  const typeRegex = /(?:type|interface)\s+(\w+)\s*[=<]/g;
+  const allMatches = [];
+  if (target === "all" || target === "function") {
+    for (const m of content.matchAll(functionRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[2] ?? "",
+        type: "function",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+    for (const m of content.matchAll(arrowRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[2] ?? "",
+        type: "arrow",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  if (target === "all" || target === "class") {
+    for (const m of content.matchAll(classRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: "",
+        type: "class",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  if (target === "all" || target === "type") {
+    for (const m of content.matchAll(typeRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({
+        name: m[1],
+        sig: m[0] ?? "",
+        type: "type",
+        line: content.slice(0, m.index).split("\n").length
+      });
+    }
+  }
+  for (const m of allMatches) {
+    results.push({
+      path: absPath,
+      name: m.name,
+      signature: m.sig,
+      docstring: `/** ${m.name} - documented at line ${m.line} */`,
+      status: "skipped"
+    });
+  }
+  return results;
+}
+
+export {
+  documentTool
+};
+//# sourceMappingURL=chunk-EMRGN4KM.js.map

package/dist/chunk-FQZOHLG3.js

@@ -0,0 +1,89 @@
+// src/_syntax-check.ts
+import * as path from "node:path";
+var TS_LIKE = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+var MAX_CHECK_CHARS = 15e5;
+var MAX_ERRORS = 5;
+var tsLoad = null;
+function loadTypescript() {
+  tsLoad ??= import("@typescript/typescript6").then(
+    (m) => m.default ?? m,
+    () => null
+  );
+  return tsLoad;
+}
+async function checkSyntax(filePath, content, previousContent) {
+  const errors = await parseErrors(filePath, content);
+  if (errors === void 0) return void 0;
+  if (errors.length === 0) return { errors, preExisting: false };
+  let preExisting = false;
+  if (previousContent !== void 0) {
+    const prevErrors = await parseErrors(filePath, previousContent);
+    preExisting = prevErrors !== void 0 && prevErrors.length > 0;
+  }
+  return { errors, preExisting };
+}
+function isJsoncFile(filePath) {
+  const base = path.basename(filePath).toLowerCase();
+  if (base.endsWith(".jsonc")) return true;
+  if (/^(tsconfig|jsconfig)([.-].*)?\.json$/.test(base)) return true;
+  const dir = path.basename(path.dirname(filePath)).toLowerCase();
+  return dir === ".vscode";
+}
+async function parseErrors(filePath, content) {
+  if (content.length > MAX_CHECK_CHARS) return void 0;
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".json" || ext === ".jsonc") {
+    try {
+      JSON.parse(content);
+      return [];
+    } catch (err) {
+      if (isJsoncFile(filePath)) {
+        const ts2 = await loadTypescript();
+        if (ts2) {
+          const jsonc = ts2.parseConfigFileTextToJson(filePath, content);
+          if (!jsonc.error) return [];
+          return [formatDiag(ts2, jsonc.error, content)];
+        }
+      }
+      return [`JSON parse error: ${err.message}`];
+    }
+  }
+  if (!TS_LIKE.has(ext)) return void 0;
+  const ts = await loadTypescript();
+  if (!ts) return void 0;
+  const scriptKind = ext === ".tsx" ? ts.ScriptKind.TSX : ext === ".ts" || ext === ".mts" || ext === ".cts" ? ts.ScriptKind.TS : (
+    // Plain JS may legitimately contain JSX; the JSX grammar is a
+    // superset for untyped code, so parsing .js/.jsx as JSX avoids
+    // false positives on React files.
+    ts.ScriptKind.JSX
+  );
+  const sourceFile = ts.createSourceFile(
+    path.basename(filePath),
+    content,
+    ts.ScriptTarget.Latest,
+    /* setParentNodes */
+    false,
+    scriptKind
+  );
+  const diags = sourceFile.parseDiagnostics ?? [];
+  return diags.slice(0, MAX_ERRORS).map((d) => formatDiag(ts, d, content, sourceFile));
+}
+function formatDiag(ts, diag, content, sourceFile) {
+  const message = ts.flattenDiagnosticMessageText(diag.messageText, " ");
+  if (diag.start === void 0) return message;
+  let line;
+  if (sourceFile) {
+    line = sourceFile.getLineAndCharacterOfPosition(diag.start).line + 1;
+  } else {
+    line = 1;
+    for (let i = 0; i < diag.start && i < content.length; i++) {
+      if (content.charCodeAt(i) === 10) line++;
+    }
+  }
+  return `line ${line}: ${message}`;
+}
+
+export {
+  checkSyntax
+};
+//# sourceMappingURL=chunk-FQZOHLG3.js.map

package/dist/chunk-GOIZNNOA.js

@@ -0,0 +1,221 @@
+// src/skill.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  missingRequiredRuntimeTools,
+  missingRuntimeCapabilities,
+  runtimeToolReferencesFromText
+} from "@wrongstack/core/agent-catalog";
+import { SKILL_LIMITS, stripFrontmatter } from "@wrongstack/core/skills";
+import { ToolValidationError } from "@wrongstack/core/types";
+var MAX_BODY_CHARS = SKILL_LIMITS.MAX_SKILL_BODY_CHARS;
+var MAX_RESOURCE_CHARS = SKILL_LIMITS.MAX_RESOURCE_CHARS;
+var MAX_LISTED_RESOURCES = SKILL_LIMITS.MAX_LISTED_RESOURCES;
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build"]);
+function makeSkillTool(skillLoader) {
+  return {
+    name: "skill",
+    category: "Skills",
+    description: "Load a skill's instructions or a bundled resource on demand (agentskills.io progressive disclosure). With only `name`: returns the SKILL.md body + a list of bundled resource files. With `name` + `resource` (a relative path like `references/REF.md` or `scripts/extract.py`): returns that file content. Prefer this over the read tool for skill files \u2014 it reaches foreign skills outside the project root.",
+    usageHint: 'Load a skill body or one of its bundled resources (progressive disclosure).\n\nWHEN TO USE:\n- A task matches a skill trigger \u2192 load the body: skill({ name })\n- You need a reference/template/script bundled with the skill \u2192 skill({ name, resource: "references/REF.md" })\n\nThe body call lists every bundled resource; load the ones you need. Run scripts via bash using the returned abs path.',
+    permission: "auto",
+    mutating: false,
+    capabilities: ["fs.read"],
+    icon: "document",
+    timeoutMs: 5e3,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Exact skill name (as shown in the available-skills list)."
+        },
+        resource: {
+          type: "string",
+          description: "Optional relative path of a bundled resource to load (e.g. references/REF.md, scripts/extract.py, assets/template.html). Omit to list resources."
+        }
+      },
+      required: ["name"]
+    },
+    async execute(input, ctx) {
+      const name = input?.name?.trim();
+      if (!name) {
+        throw new ToolValidationError({ message: "skill: name is required", field: "name" });
+      }
+      const manifest = await skillLoader.find(name);
+      if (!manifest) {
+        throw new ToolValidationError({
+          message: `skill "${name}" not found \u2014 use /skill to list available skills`,
+          field: "name"
+        });
+      }
+      const availableToolNames = (ctx?.catalogTools ?? ctx?.tools ?? []).map((tool) => tool.name);
+      const missingCapabilities = missingRuntimeCapabilities(
+        manifest.requiredCapabilities,
+        availableToolNames
+      );
+      const missingTools = missingRequiredRuntimeTools(manifest.requiredTools, availableToolNames);
+      if (missingCapabilities.length > 0 || missingTools.length > 0) {
+        throw new ToolValidationError({
+          message: `skill "${name}" is unavailable in this runtime; ` + [
+            missingCapabilities.length > 0 ? `missing capabilities: ${missingCapabilities.join(", ")}` : "",
+            missingTools.length > 0 ? `missing tools: ${missingTools.join(", ")}` : ""
+          ].filter(Boolean).join("; "),
+          field: "name"
+        });
+      }
+      const dir = path.dirname(manifest.path);
+      let loadedResource;
+      if (input.resource?.trim()) {
+        loadedResource = await loadResource(dir, input.resource.trim());
+      }
+      const raw = await skillLoader.readBody(name);
+      const missingBodyTools = missingRequiredRuntimeTools(
+        runtimeToolReferencesFromText(raw),
+        availableToolNames
+      );
+      const warning = missingBodyTools.length > 0 ? `Warning: skill "${name}" references tools not registered in this runtime: ${missingBodyTools.join(", ")}. Steps that call them may be unavailable.` : void 0;
+      const body = stripFrontmatter(raw).trim().slice(0, MAX_BODY_CHARS);
+      const resources = loadedResource ? [] : await listResources(dir);
+      try {
+        await ctx?.session?.append({
+          type: "skill_activated",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          skillName: manifest.name
+        });
+      } catch {
+      }
+      return {
+        name: manifest.name,
+        description: manifest.description,
+        body,
+        resources,
+        dir,
+        loadedResource,
+        warning
+      };
+    },
+    serialize(output) {
+      const warningLine = output.warning ? `
+
+${output.warning}` : "";
+      if (output.loadedResource) {
+        const lr = output.loadedResource;
+        const note = lr.truncated ? ` (truncated to ${lr.content.length} chars of ${lr.bytes} B)` : "";
+        return `# Resource: ${output.name}/${lr.rel}
+(abs path: ${lr.absPath})${note}
+
+${lr.content}${warningLine}`;
+      }
+      const head = `# Skill: ${output.name}
+${output.description}
+
+${output.body}`;
+      if (output.resources.length === 0) return `${head}${warningLine}`;
+      const listing = output.resources.map((r) => `- ${r.path} (${r.bytes} B)`).join("\n");
+      return `${head}
+
+## Bundled resources (load on demand)
+Load any with: \`skill({ name: "${output.name}", resource: "<path>" })\`. Run scripts via bash using their abs path under ${output.dir}.
+${listing}${warningLine}`;
+    }
+  };
+}
+async function loadResource(skillDir, rel) {
+  const norm = rel.replace(/\\/g, "/");
+  if (path.isAbsolute(rel) || norm.split("/").some((seg) => seg === "..")) {
+    throw new ToolValidationError({
+      message: `skill: invalid resource path "${rel}"`,
+      field: "resource"
+    });
+  }
+  const absPath = path.resolve(skillDir, rel);
+  const root = path.resolve(skillDir);
+  if (absPath !== root && !absPath.startsWith(root + path.sep)) {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" escapes the skill directory`,
+      field: "resource"
+    });
+  }
+  let realPath;
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(root);
+    realPath = await fs.realpath(absPath);
+  } catch {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" not readable`,
+      field: "resource"
+    });
+  }
+  if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" resolves outside the skill directory`,
+      field: "resource"
+    });
+  }
+  let buf;
+  try {
+    buf = await fs.readFile(realPath);
+  } catch {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" not readable`,
+      field: "resource"
+    });
+  }
+  const raw = buf.toString("utf8");
+  const truncated = raw.length > MAX_RESOURCE_CHARS;
+  return {
+    rel: norm,
+    // The canonical path — the one actually opened, and the one a follow-up
+    // `bash` invocation should use.
+    absPath: realPath,
+    content: truncated ? raw.slice(0, MAX_RESOURCE_CHARS) : raw,
+    bytes: buf.length,
+    truncated
+  };
+}
+async function listResources(skillDir) {
+  const out = [];
+  await walk(skillDir, skillDir, out);
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out.slice(0, MAX_LISTED_RESOURCES);
+}
+async function walk(root, dir, out) {
+  if (out.length >= MAX_LISTED_RESOURCES) return;
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (out.length >= MAX_LISTED_RESOURCES) return;
+    const fullPath = path.join(dir, e.name);
+    let isDir = e.isDirectory();
+    if (e.isSymbolicLink()) {
+      try {
+        isDir = (await fs.stat(fullPath)).isDirectory();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
+      if (SKIP_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+      await walk(root, fullPath, out);
+    } else if (e.isFile()) {
+      if (e.name === "SKILL.md" || e.name === "SKILL.save.md") continue;
+      try {
+        const stat2 = await fs.stat(fullPath);
+        const rel = path.relative(root, fullPath).split(path.sep).join("/");
+        out.push({ path: rel, bytes: stat2.size });
+      } catch {
+      }
+    }
+  }
+}
+
+export {
+  makeSkillTool
+};
+//# sourceMappingURL=chunk-GOIZNNOA.js.map