@zackbart/connecta 0.10.1 → 0.10.3

package/src/validate.ts

@@ -1,5 +1,10 @@
 import { Validator } from "@cfworker/json-schema";
 import { ConnectorCallError } from "./errors.js";
+import type {
+  ArgumentValidationDetails,
+  ArgumentValidationIssue,
+} from "./errors.js";
+import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
 import type { JsonSchema, Logger } from "./types.js";
 
 export interface ValidateToolInputOptions {
@@ -42,6 +47,128 @@ export interface PrecompileValidatorOptions {
 // breaking a working tool). A WeakMap so schemas belonging to a discarded
 // connector are collectable, the same pattern compactSchema uses.
 const validators = new WeakMap<JsonSchema, Validator | null>();
+const REQUIRED_PROPERTY_RE =
+  /^Instance does not have required property "([^"]+)"\.$/;
+
+interface ValidationUnit {
+  keyword: string;
+  keywordLocation: string;
+  instanceLocation: string;
+  error: string;
+}
+
+function decodePointerPart(value: string): string {
+  return value.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function encodePointerPart(value: string): string {
+  return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function pointerValue(value: unknown, pointer: string): unknown {
+  if (pointer === "#") return value;
+  if (!pointer.startsWith("#/")) return undefined;
+  let current = value;
+  for (const part of pointer.slice(2).split("/").map(decodePointerPart)) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function argumentPath(location: string): string {
+  if (location === "#") return "/";
+  return location.startsWith("#") ? location.slice(1) || "/" : "/";
+}
+
+function expectedType(schema: JsonSchema, unit: ValidationUnit): string | undefined {
+  if (unit.keyword === "type") {
+    const value = pointerValue(schema, unit.keywordLocation);
+    if (typeof value === "string") return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+      return value.join(" | ");
+    }
+  }
+  if (unit.keyword === "required") {
+    const missing = REQUIRED_PROPERTY_RE.exec(unit.error)?.[1];
+    if (!missing) return undefined;
+    const parentLocation = unit.keywordLocation.replace(/\/required$/, "");
+    const value = pointerValue(
+      schema,
+      `${parentLocation}/properties/${encodePointerPart(missing)}/type`,
+    );
+    if (typeof value === "string") return value;
+    if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+      return value.join(" | ");
+    }
+    return "present";
+  }
+  const fixed: Record<string, string> = {
+    additionalProperties: "no additional properties",
+    enum: "one of the declared values",
+    const: "the declared constant",
+    minLength: "the declared minimum length",
+    maxLength: "the declared maximum length",
+    minimum: "the declared minimum",
+    maximum: "the declared maximum",
+    pattern: "the declared string pattern",
+  };
+  return fixed[unit.keyword];
+}
+
+function validationDetails(
+  schema: JsonSchema,
+  units: ValidationUnit[],
+): ArgumentValidationDetails {
+  const leafUnits = units.filter(
+    (unit) =>
+      ![
+        "properties",
+        "items",
+        "allOf",
+        "anyOf",
+        "oneOf",
+        "if",
+        "not",
+        "patternProperties",
+        "additionalProperties",
+      ].includes(unit.keyword),
+  );
+  const issues: ArgumentValidationIssue[] = [];
+  for (const unit of leafUnits) {
+    const missing =
+      unit.keyword === "required"
+        ? REQUIRED_PROPERTY_RE.exec(unit.error)?.[1]
+        : undefined;
+    const path =
+      missing !== undefined
+        ? `${argumentPath(unit.instanceLocation).replace(/\/$/, "")}/${encodePointerPart(missing)}`
+        : argumentPath(unit.instanceLocation);
+    const code = unit.keyword === "false" ? "additionalProperties" : unit.keyword;
+    const expected =
+      expectedType(schema, unit) ??
+      (code === "additionalProperties"
+        ? "no additional properties"
+        : "the declared schema constraint");
+    const issue = { path, code, expected };
+    if (
+      !issues.some(
+        (existing) =>
+          existing.path === issue.path &&
+          existing.code === issue.code &&
+          existing.expected === issue.expected,
+      )
+    ) {
+      issues.push(issue);
+    }
+  }
+  return {
+    issues: issues.slice(0, MAX_ARGUMENT_VALIDATION_ISSUES),
+    ...(issues.length > MAX_ARGUMENT_VALIDATION_ISSUES
+      ? { truncated: true as const }
+      : {}),
+  };
+}
 
 function unevaluableSchema(address: string): ConnectorCallError {
   return new ConnectorCallError(
@@ -127,6 +254,7 @@ export function validateToolInput(
     return new ConnectorCallError(
       "invalid_args",
       `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`,
+      { validation: validationDetails(schema, result.errors) },
     );
   }
   return null;

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.10.1";
+export const CONNECTA_VERSION = "0.10.3";

package/templates/node/.env.example

@@ -0,0 +1,5 @@
+# Required. Use a long random value and keep it out of source control.
+CONNECTA_TOKEN=replace-me
+
+# Optional. Defaults to 8787.
+PORT=8787

package/templates/node/AGENTS.md

@@ -0,0 +1,19 @@
+# Working on this Connecta deployment
+
+This repository is deployment configuration, not a copy of Connecta itself.
+
+- Edit `src/index.ts` for connectors, authentication, storage, and public URL.
+- Keep `executor: quickJsExecutor()` for the prescribed seven-tool code-first
+  surface.
+- Keep credentials in environment variables or an external secret store.
+  Never commit `.env`, `.connecta-state.json`, tokens, or credential values.
+- Add application logic only inside deliberate `api()` connector handlers.
+  Do not copy or modify Connecta package internals here.
+- Prefer `api()` when the agent must see an exact reviewed capability surface;
+  `remoteMcp()` follows the downstream server's evolving tool catalog.
+- Run `npm run typecheck` after configuration changes. With the server running,
+  run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
+
+Do not add alternate entrypoints, policy layers, generated connector catalogs,
+or runtime connector registration. Keep the deployment small enough to review
+as configuration.

package/templates/node/README.md

@@ -0,0 +1,33 @@
+# Connecta deployment
+
+This is the prescribed small Node deployment. Install and run it:
+
+```sh
+npm install
+CONNECTA_TOKEN=dev-token npm start
+```
+
+Then point an MCP client at `http://localhost:8787/mcp` with
+`Authorization: Bearer dev-token`.
+
+## Deployment contract
+
+- Edit `src/index.ts` for connectors, auth, storage, and the public URL.
+- Keep `executor: quickJsExecutor()` for the seven-tool code-first surface.
+- Keep secrets in environment variables or an external secret store.
+- Add application code only inside deliberate `api()` connector handlers.
+- Do not copy Connecta package internals into this deployment.
+- `AGENTS.md` is the canonical convention file; `CLAUDE.md` points to it.
+
+Verify a change with:
+
+```sh
+npm run typecheck
+# In another terminal, while npm start is running:
+CONNECTA_TOKEN=dev-token npm run doctor
+```
+
+Doctor checks health, the executor, and the exact prescribed seven-tool
+model-facing surface by running a harmless sandbox program. It reads the bearer
+from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
+Remote URLs must use HTTPS.

package/templates/node/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "connecta-deployment",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "doctor": "connecta doctor",
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zackbart/connecta": "0.10.3",
+    "quickjs-emscripten": "0.32.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.23.1",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/node/src/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Prescribed Connecta deployment.
+ *
+ * Keep this file as deployment configuration: connectors, authentication,
+ * storage, and public origin. Add application logic only inside deliberate
+ * api() connector handlers.
+ */
+import { api, bearerToken, createConnecta } from "@zackbart/connecta";
+import { fileStorage, listen } from "@zackbart/connecta/node";
+import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+
+const token = process.env.CONNECTA_TOKEN;
+if (!token) {
+  throw new Error(
+    "CONNECTA_TOKEN is required. Refusing to start without inbound auth.",
+  );
+}
+const port = Number(process.env.PORT ?? 8787);
+
+const connecta = createConnecta({
+  storage: fileStorage("./.connecta-state.json"),
+  auth: bearerToken(token, { subjectId: "operator" }),
+  publicUrl: `http://localhost:${port}`,
+  // Keep this for the prescribed seven-tool code-first surface.
+  executor: quickJsExecutor(),
+  connectors: [
+    api("time", {
+      description: "Time — current timestamp",
+      tools: [
+        {
+          name: "get_now",
+          description: "Return the current time as an ISO 8601 timestamp.",
+          inputSchema: { type: "object", properties: {} },
+          annotations: { readOnlyHint: true },
+          handler: async () => ({ now: new Date().toISOString() }),
+        },
+      ],
+    }),
+  ],
+});
+
+listen(connecta, port);
+console.log(`connecta listening on http://localhost:${port}/mcp`);

package/templates/node/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}