@skastr0/quartz-opencode-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guilherme Castro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @skastr0/quartz-opencode-plugin
+
+OpenCode plugin wrapper for Quartz TypeScript code intelligence.
+
+## Status
+
+Experimental. The plugin is publishable as a Bun/ESM package, but the repository is still using explicit release gates before any real npm upload.
+
+## Install
+
+After the first npm release:
+
+```bash
+bun add -d @skastr0/quartz-opencode-plugin
+```
+
+The package exports `@skastr0/quartz-opencode-plugin/server`.
+
+## Build
+
+```bash
+bun run build
+```
+
+The bundle is written to `dist/server.js` and exported as `@skastr0/quartz-opencode-plugin/server`.
+
+## Runtime Behavior
+
+The plugin roots Quartz at the OpenCode workspace directory. It creates one Effect runtime, reuses the analyzer across tool calls, and marks the analyzer cache dirty after file-modifying tools such as `edit`, `write`, or `morph-mcp_edit_file`.
+
+Use the optional `package` argument when the workspace has multiple discovered TypeScript packages.
+
+## Tools
+
+Discovery:
+
+- `type_packages`
+- `type_symbols`
+- `type_info`
+- `type_expand`
+- `type_related`
+- `type_search`
+
+Analysis:
+
+- `type_eval`
+- `type_diagnostics`
+- `type_check_snippet`
+- `type_at_position`
+- `type_file`
+- `type_refresh`
+
+Relationships and refactors:
+
+- `type_compatible`
+- `type_graph`
+- `type_refactor_preview`
+- `type_why_error`
+- `type_explain`
+- `type_transform_search`
+
+## Examples
+
+```json
+{"tool":"type_symbols","args":{"pattern":"^User","kind":"interface","limit":10}}
+```
+
+```json
+{"tool":"type_info","args":{"symbol":"User"}}
+```
+
+```json
+{"tool":"type_transform_search","args":{"from":"User","to":"UserDTO","limit":5}}
+```
+
+The plugin returns JSON strings for most tool results, matching the core analyzer data shapes. `type_refresh` clears cached TypeScript projects and returns the analyzer refresh result.

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const QuartzPlugin: Plugin;
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;

package/dist/server.js

@@ -0,0 +1,351 @@
+// @bun
+// src/server.ts
+import { tool } from "@opencode-ai/plugin";
+import { Effect, ManagedRuntime } from "effect";
+import { CoreLayer, TypeAnalyzerService } from "@skastr0/quartz-core";
+var run = (effect) => Effect.runPromise(effect.pipe(Effect.mapError((error) => error instanceof Error ? error : new Error(String(error)))));
+var optionalPackageArg = tool.schema.string().optional().describe("Package/directory to analyze. Omit for root or single-package projects.");
+var limitArg = tool.schema.number().optional().describe("Maximum number of results");
+var json = (value) => JSON.stringify(value, null, 2);
+var FILE_MODIFYING_TOOLS = new Set(["edit", "morph-mcp_edit_file", "write"]);
+var packageOption = (packageName) => packageName === undefined ? {} : { packageName };
+var optionalOption = (key, value) => value === undefined ? {} : { [key]: value };
+var createDiscoveryTools = (analyzer) => ({
+  type_packages: tool({
+    description: "List TypeScript packages discovered from tsconfig.json files.",
+    args: {},
+    async execute() {
+      return json(await run(analyzer.getPackages()));
+    }
+  }),
+  type_symbols: tool({
+    description: "List exported TypeScript symbols.",
+    args: {
+      package: optionalPackageArg,
+      pattern: tool.schema.string().optional().describe("Case-insensitive regex pattern"),
+      kind: tool.schema.string().optional().describe("Symbol kind, such as interface, type, class, or function"),
+      limit: limitArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.listSymbols({
+        ...packageOption(args.package),
+        ...optionalOption("pattern", args.pattern),
+        ...optionalOption("kind", args.kind),
+        ...optionalOption("limit", args.limit)
+      })));
+    }
+  }),
+  type_info: tool({
+    description: "Show type information for an exported TypeScript symbol.",
+    args: {
+      symbol: tool.schema.string().describe("Exported symbol name"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.getTypeInfo(args.symbol, args.package)));
+    }
+  }),
+  type_expand: tool({
+    description: "Expand an exported TypeScript symbol type.",
+    args: {
+      symbol: tool.schema.string().describe("Exported symbol name"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.expandType(args.symbol, args.package)));
+    }
+  }),
+  type_related: tool({
+    description: "Find types that reference or are referenced by a TypeScript symbol.",
+    args: {
+      symbol: tool.schema.string().describe("Exported symbol name"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.findRelated(args.symbol, args.package)));
+    }
+  }),
+  type_search: tool({
+    description: "Search exported types by name, property, or base type.",
+    args: {
+      query: tool.schema.string().describe("Case-insensitive symbol query"),
+      package: optionalPackageArg,
+      pattern: tool.schema.string().optional().describe("Case-insensitive regex pattern"),
+      hasProperty: tool.schema.string().optional().describe("Only include types with this property"),
+      extends: tool.schema.string().optional().describe("Only include types extending this base symbol"),
+      limit: limitArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.searchTypes({
+        query: args.query,
+        ...optionalOption("pattern", args.pattern),
+        ...optionalOption("hasProperty", args.hasProperty),
+        ...optionalOption("extends", args.extends),
+        ...packageOption(args.package),
+        ...optionalOption("limit", args.limit)
+      })));
+    }
+  })
+});
+var createAnalysisTools = (analyzer) => ({
+  type_eval: tool({
+    description: "Evaluate a TypeScript type expression and return the computed type.",
+    args: {
+      expression: tool.schema.string().describe("TypeScript type expression"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.evalType(args.expression, args.package)));
+    }
+  }),
+  type_diagnostics: tool({
+    description: "Show TypeScript diagnostics.",
+    args: {
+      package: optionalPackageArg,
+      explain: tool.schema.boolean().optional().describe("Include explanations for diagnostics")
+    },
+    async execute(args) {
+      return json(await run(analyzer.getDiagnostics({
+        ...packageOption(args.package),
+        ...optionalOption("explain", args.explain)
+      })));
+    }
+  }),
+  type_check_snippet: tool({
+    description: "Type-check a TypeScript code snippet without writing to disk.",
+    args: {
+      code: tool.schema.string().describe("TypeScript code snippet"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.checkSnippet(args.code, args.package)));
+    }
+  }),
+  type_at_position: tool({
+    description: "Show the type at a TypeScript source position.",
+    args: {
+      file: tool.schema.string().describe("TypeScript file path"),
+      line: tool.schema.number().describe("One-based line number"),
+      column: tool.schema.number().describe("One-based column number"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.getTypeAtPosition(args.file, args.line, args.column, args.package)));
+    }
+  }),
+  type_file: tool({
+    description: "Inspect declarations in a specific TypeScript file.",
+    args: {
+      file: tool.schema.string().describe("TypeScript file path"),
+      symbol: tool.schema.string().optional().describe("Optional declaration name regex"),
+      includePrivate: tool.schema.boolean().optional().describe("Include non-exported declarations"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.getFileDeclarations(args.file, {
+        ...packageOption(args.package),
+        ...optionalOption("symbol", args.symbol),
+        ...optionalOption("includePrivate", args.includePrivate)
+      })));
+    }
+  }),
+  type_refresh: tool({
+    description: "Clear cached TypeScript projects to pick up external file changes.",
+    args: {
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return await run(analyzer.refresh(args.package));
+    }
+  })
+});
+var createRelationshipTools = (analyzer) => ({
+  ...createCompatibilityTools(analyzer),
+  ...createGraphTools(analyzer),
+  ...createRefactorTools(analyzer),
+  ...createExplanationTools(analyzer),
+  ...createTransformSearchTools(analyzer),
+  ...createVerifyContractTools(analyzer)
+});
+var createCompatibilityTools = (analyzer) => ({
+  type_compatible: tool({
+    description: "Check if one type is assignable to another.",
+    args: {
+      from: tool.schema.string().describe("Source type or symbol"),
+      to: tool.schema.string().describe("Target type or symbol"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.checkCompatibility(args.from, args.to, args.package)));
+    }
+  })
+});
+var createGraphTools = (analyzer) => ({
+  type_graph: tool({
+    description: "Generate a type dependency graph as Mermaid or DOT.",
+    args: {
+      symbol: tool.schema.string().describe("Root symbol"),
+      depth: tool.schema.number().optional().describe("Traversal depth"),
+      format: tool.schema.enum(["mermaid", "dot"]).optional().describe("Graph output format"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.generateGraph(args.symbol, {
+        ...packageOption(args.package),
+        ...optionalOption("depth", args.depth),
+        ...optionalOption("format", args.format)
+      })));
+    }
+  })
+});
+var createRefactorTools = (analyzer) => ({
+  type_refactor_preview: tool({
+    description: "Preview a rename refactor without applying it.",
+    args: {
+      symbol: tool.schema.string().describe("Symbol to rename"),
+      to: tool.schema.string().describe("New name"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.previewRefactor({
+        action: "rename",
+        symbol: args.symbol,
+        to: args.to,
+        ...packageOption(args.package)
+      })));
+    }
+  })
+});
+var createExplanationTools = (analyzer) => ({
+  type_why_error: tool({
+    description: "Explain a TypeScript diagnostic in human terms.",
+    args: {
+      code: tool.schema.number().optional().describe("TypeScript diagnostic code"),
+      message: tool.schema.string().optional().describe("Diagnostic message"),
+      file: tool.schema.string().optional().describe("File path with the diagnostic"),
+      line: tool.schema.number().optional().describe("One-based diagnostic line"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.explainError({
+        ...packageOption(args.package),
+        ...optionalOption("code", args.code),
+        ...optionalOption("message", args.message),
+        ...optionalOption("file", args.file),
+        ...optionalOption("line", args.line)
+      })));
+    }
+  }),
+  type_explain: tool({
+    description: "Show step-by-step resolution of a complex TypeScript type expression.",
+    args: {
+      expression: tool.schema.string().describe("TypeScript type expression"),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.explainType(args.expression, args.package)));
+    }
+  })
+});
+var createTransformSearchTools = (analyzer) => ({
+  type_transform_search: tool({
+    description: "Search for functions by structural input/output type compatibility.",
+    args: {
+      from: tool.schema.string().optional().describe("Input type"),
+      to: tool.schema.string().optional().describe("Output type"),
+      paramPosition: tool.schema.union([tool.schema.number(), tool.schema.literal("any")]).optional(),
+      unwrapReturn: tool.schema.boolean().optional(),
+      exportedOnly: tool.schema.boolean().optional(),
+      limit: limitArg,
+      allowTypeErasure: tool.schema.boolean().optional(),
+      verifiedOnly: tool.schema.boolean().optional(),
+      minVerificationStatus: tool.schema.enum(["verified", "unverified", "unverifiable"]).optional().describe("Minimum verification status to return"),
+      includeDiagnostics: tool.schema.boolean().optional(),
+      includeSyntheticCode: tool.schema.boolean().optional(),
+      includeFailedVerification: tool.schema.boolean().optional(),
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return await run(analyzer.transformSearch({
+        ...packageOption(args.package),
+        ...optionalOption("from", args.from),
+        ...optionalOption("to", args.to),
+        ...optionalOption("paramPosition", args.paramPosition),
+        ...optionalOption("unwrapReturn", args.unwrapReturn),
+        ...optionalOption("exportedOnly", args.exportedOnly),
+        ...optionalOption("limit", args.limit),
+        ...optionalOption("allowTypeErasure", args.allowTypeErasure),
+        ...optionalOption("verifiedOnly", args.verifiedOnly),
+        ...optionalOption("minVerificationStatus", args.minVerificationStatus),
+        ...optionalOption("includeDiagnostics", args.includeDiagnostics),
+        ...optionalOption("includeSyntheticCode", args.includeSyntheticCode),
+        ...optionalOption("includeFailedVerification", args.includeFailedVerification)
+      }));
+    }
+  })
+});
+var createVerifyContractTools = (analyzer) => ({
+  type_verify_contract: tool({
+    description: "Compose compatibility, snippet, diagnostics, and transform evidence for a proposed type contract.",
+    args: {
+      from: tool.schema.string().optional().describe("Source type or symbol"),
+      to: tool.schema.string().optional().describe("Target type or symbol"),
+      symbol: tool.schema.string().optional().describe("Expected transform symbol"),
+      snippet: tool.schema.string().optional().describe("Concrete TypeScript call-site snippet to check"),
+      includeDiagnostics: tool.schema.boolean().optional(),
+      includeTransformEvidence: tool.schema.boolean().optional(),
+      transformLimit: limitArg,
+      package: optionalPackageArg
+    },
+    async execute(args) {
+      return json(await run(analyzer.verifyContract({
+        ...packageOption(args.package),
+        ...optionalOption("from", args.from),
+        ...optionalOption("to", args.to),
+        ...optionalOption("symbol", args.symbol),
+        ...optionalOption("snippet", args.snippet),
+        ...optionalOption("includeDiagnostics", args.includeDiagnostics),
+        ...optionalOption("includeTransformEvidence", args.includeTransformEvidence),
+        ...optionalOption("transformLimit", args.transformLimit)
+      })));
+    }
+  })
+});
+var createToolDefinitions = (analyzer) => ({
+  ...createDiscoveryTools(analyzer),
+  ...createAnalysisTools(analyzer),
+  ...createRelationshipTools(analyzer)
+});
+var QuartzPlugin = async (ctx) => {
+  const runtime = ManagedRuntime.make(CoreLayer(ctx.directory));
+  const analyzer = runtime.runSync(TypeAnalyzerService);
+  const client = ctx.client;
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        await client.app?.log?.({
+          body: {
+            service: "quartz",
+            level: "debug",
+            message: "session idle observed by quartz plugin",
+            extra: { sessionID: event.properties.sessionID }
+          }
+        });
+      }
+    },
+    "tool.execute.after": async (input) => {
+      if (FILE_MODIFYING_TOOLS.has(input.tool)) {
+        await run(analyzer.markDirty());
+      }
+    },
+    tool: createToolDefinitions(analyzer)
+  };
+};
+var server_default = {
+  id: "quartz",
+  server: QuartzPlugin
+};
+export {
+  server_default as default,
+  QuartzPlugin
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@skastr0/quartz-opencode-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/server.ts --outdir ./dist --target bun --format esm --external @opencode-ai/plugin --external @skastr0/quartz-core --external effect && tsc -p tsconfig.build.json",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@skastr0/quartz-core": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.4.0"
+  },
+  "license": "MIT",
+  "description": "OpenCode plugin wrapper for quartz TypeScript code intelligence.",
+  "keywords": [
+    "quartz",
+    "opencode",
+    "plugin",
+    "typescript",
+    "code-intelligence",
+    "agent-tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skastr0/quartz.git",
+    "directory": "apps/opencode-plugin"
+  },
+  "homepage": "https://github.com/skastr0/quartz#readme",
+  "bugs": {
+    "url": "https://github.com/skastr0/quartz/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}