@neon/tools 2.15.0 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/README.md +120 -5
  2. package/dist/descriptions.gen.js +2 -2
  3. package/dist/generated/output.gen.d.ts +1 -0
  4. package/dist/generated/output.gen.d.ts.map +1 -1
  5. package/dist/generated/output.gen.js +2 -1
  6. package/dist/generated/zod.gen.d.ts +11 -3
  7. package/dist/generated/zod.gen.d.ts.map +1 -1
  8. package/dist/generated/zod.gen.js +6 -3
  9. package/dist/index.d.ts +17 -5
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +30 -9
  12. package/dist/lib/caller-error.d.ts +16 -0
  13. package/dist/lib/caller-error.d.ts.map +1 -0
  14. package/dist/lib/caller-error.js +18 -0
  15. package/dist/lib/custom/auth-config.d.ts +0 -1
  16. package/dist/lib/custom/auth-config.d.ts.map +1 -1
  17. package/dist/lib/custom/auth-config.js +13 -6
  18. package/dist/lib/custom/docs.d.ts.map +1 -1
  19. package/dist/lib/custom/docs.js +8 -6
  20. package/dist/lib/custom/feedback.d.ts.map +1 -1
  21. package/dist/lib/custom/feedback.js +1 -0
  22. package/dist/lib/custom/fetch.d.ts +1 -1
  23. package/dist/lib/custom/fetch.d.ts.map +1 -1
  24. package/dist/lib/custom/fetch.js +4 -3
  25. package/dist/lib/custom/organizations.d.ts.map +1 -1
  26. package/dist/lib/custom/organizations.js +1 -0
  27. package/dist/lib/custom/resources.d.ts.map +1 -1
  28. package/dist/lib/custom/resources.js +1 -0
  29. package/dist/lib/custom/sql/connection.d.ts +7 -8
  30. package/dist/lib/custom/sql/connection.d.ts.map +1 -1
  31. package/dist/lib/custom/sql/connection.js +12 -14
  32. package/dist/lib/custom/sql/describe-branch.js +2 -2
  33. package/dist/lib/custom/sql/inspect/inspect.d.ts.map +1 -1
  34. package/dist/lib/custom/sql/inspect/inspect.js +5 -5
  35. package/dist/lib/custom/sql/inspect/targets.js +3 -3
  36. package/dist/lib/custom/sql/migrations.d.ts.map +1 -1
  37. package/dist/lib/custom/sql/migrations.js +3 -5
  38. package/dist/lib/custom/sql/plan.d.ts +2 -0
  39. package/dist/lib/custom/sql/plan.d.ts.map +1 -1
  40. package/dist/lib/custom/sql/plan.js +19 -6
  41. package/dist/lib/custom/sql/query-tuning.d.ts.map +1 -1
  42. package/dist/lib/custom/sql/query-tuning.js +9 -7
  43. package/dist/lib/custom/sql/run.d.ts.map +1 -1
  44. package/dist/lib/custom/sql/run.js +4 -5
  45. package/dist/lib/custom/sql/schema.d.ts.map +1 -1
  46. package/dist/lib/custom/sql/schema.js +6 -6
  47. package/dist/lib/custom/sql/slow-queries.d.ts.map +1 -1
  48. package/dist/lib/custom/sql/slow-queries.js +8 -3
  49. package/dist/lib/customize.d.ts +1 -1
  50. package/dist/lib/customize.d.ts.map +1 -1
  51. package/dist/lib/customize.js +8 -4
  52. package/dist/lib/effect/tools.d.ts.map +1 -1
  53. package/dist/lib/effect/tools.js +2 -1
  54. package/dist/lib/ergonomic/bind.d.ts +10 -6
  55. package/dist/lib/ergonomic/bind.d.ts.map +1 -1
  56. package/dist/lib/ergonomic/bind.js +11 -2
  57. package/dist/lib/ergonomic/catalog.d.ts +8 -12
  58. package/dist/lib/ergonomic/catalog.d.ts.map +1 -1
  59. package/dist/lib/ergonomic/catalog.js +102 -23
  60. package/dist/lib/ergonomic/composed.d.ts.map +1 -1
  61. package/dist/lib/ergonomic/composed.js +29 -0
  62. package/dist/lib/mcp-json-schema.d.ts.map +1 -1
  63. package/dist/lib/mcp-json-schema.js +15 -1
  64. package/dist/lib/operation.d.ts +50 -4
  65. package/dist/lib/operation.d.ts.map +1 -1
  66. package/dist/lib/operation.js +6 -1
  67. package/dist/lib/policy.d.ts +24 -0
  68. package/dist/lib/policy.d.ts.map +1 -0
  69. package/dist/lib/policy.js +49 -0
  70. package/dist/lib/redact.d.ts +8 -0
  71. package/dist/lib/redact.d.ts.map +1 -0
  72. package/dist/lib/redact.js +40 -0
  73. package/dist/mastra.d.ts +2 -1
  74. package/dist/mastra.d.ts.map +1 -1
  75. package/dist/operations.gen.d.ts +391 -388
  76. package/dist/operations.gen.d.ts.map +1 -1
  77. package/dist/operations.gen.js +6 -4
  78. package/package.json +4 -4
package/dist/index.js CHANGED
@@ -4,6 +4,8 @@ import { InspectDiagnosticError } from "./lib/custom/sql/inspect/inspect.js";
4
4
  import { customToolIds, isNeonToolId, toolIds, unpublishedToolError } from "./lib/ergonomic/ids.js";
5
5
  import { applyToolCustomization, assertToolCustomizeOptions, publishedToolId } from "./lib/customize.js";
6
6
  import { toolFactories } from "./lib/ergonomic/catalog.js";
7
+ import { REDACTED_SECRET } from "./lib/redact.js";
8
+ import { applyToolPolicy, hiddenSecretFields, toolCallGuard, toolDescriptor, withheldUnderSecrets } from "./lib/policy.js";
7
9
  import { NeonError } from "@neon/sdk";
8
10
  // src/index.ts
9
11
  const assertKnownNameKeys = (names, tools) => {
@@ -21,16 +23,30 @@ const factoryFor = (id) => {
21
23
  if (known === void 0) throw unpublishedToolError(id);
22
24
  return toolFactories[known];
23
25
  };
24
- const bindTools = (options) => {
25
- assertToolCustomizeOptions(options);
26
- const selected = options.tools;
27
- if (selected === void 0 || selected.length === 0) throw new TypeError("createNeonTools requires at least one tool");
26
+ const publishedIdOf = (publishedIds, toolId) => {
27
+ const published = publishedIds.get(toolId);
28
+ if (published === void 0) throw new TypeError(`No published id for ${toolId}`);
29
+ return published;
30
+ };
31
+ const selectedEntries = (options) => {
32
+ const selection = options.tools;
33
+ if (typeof selection === "function") {
34
+ const entries = toolIds.map((toolId) => [toolId, factoryFor(toolId)(options)]).filter(([, tool]) => selection(toolDescriptor(tool)));
35
+ if (entries.length === 0) throw new TypeError("The createNeonTools tools predicate matched no tool");
36
+ return entries;
37
+ }
38
+ if (selection === void 0 || selection.length === 0) throw new TypeError("createNeonTools requires at least one tool");
28
39
  const seen = /* @__PURE__ */ new Set();
29
- const rawEntries = selected.map((toolId) => {
40
+ return selection.map((toolId) => {
30
41
  if (seen.has(toolId)) throw new Error(`Duplicate Neon tool "${toolId}"`);
31
42
  seen.add(toolId);
32
43
  return [toolId, factoryFor(toolId)(options)];
33
44
  });
45
+ };
46
+ const bindTools = (options) => {
47
+ assertToolCustomizeOptions(options);
48
+ const rawEntries = selectedEntries(options);
49
+ const selected = rawEntries.map(([toolId]) => toolId);
34
50
  assertKnownNameKeys(options.names, rawEntries.map(([, tool]) => tool));
35
51
  const publishedIds = /* @__PURE__ */ new Map();
36
52
  const selectorsById = /* @__PURE__ */ new Map();
@@ -41,7 +57,10 @@ const bindTools = (options) => {
41
57
  selectorsById.set(published, id);
42
58
  publishedIds.set(id, published);
43
59
  }
44
- const entries = rawEntries.map(([id, tool]) => [id, applyToolCustomization(tool, options, publishedIds)]);
60
+ const entries = rawEntries.map(([id, tool]) => {
61
+ const guard = toolCallGuard(tool, options, publishedIdOf(publishedIds, id));
62
+ return [id, applyToolCustomization(applyToolPolicy(tool, options, guard), options, publishedIds, guard)];
63
+ });
45
64
  const tools = Object.fromEntries(entries);
46
65
  assertNeonTools(tools, selected);
47
66
  return tools;
@@ -54,7 +73,9 @@ function createNeonTool(id, options) {
54
73
  assertToolCustomizeOptions(options);
55
74
  const tool = factoryFor(id)(options);
56
75
  assertKnownNameKeys(options.names, [tool]);
57
- const publishedIds = /* @__PURE__ */ new Map([[id, publishedToolId(tool, options)]]);
58
- return applyToolCustomization(tool, options, publishedIds);
76
+ const published = publishedToolId(tool, options);
77
+ const publishedIds = /* @__PURE__ */ new Map([[id, published]]);
78
+ const guard = toolCallGuard(tool, options, published);
79
+ return applyToolCustomization(applyToolPolicy(tool, options, guard), options, publishedIds, guard);
59
80
  }
60
- export { InspectDiagnosticError, NeonError, createNeonTool, createNeonTools, customToolIds, inspectChecks, publishedId, toolIds };
81
+ export { InspectDiagnosticError, NeonError, REDACTED_SECRET, createNeonTool, createNeonTools, customToolIds, hiddenSecretFields, inspectChecks, publishedId, toolIds, withheldUnderSecrets };
@@ -0,0 +1,16 @@
1
+ import { NeonClientError } from "@neon/sdk";
2
+ /**
3
+ * A `NeonClientError` a tool raises for a mistake in the call or in the
4
+ * caller's own resources: a missing page or table, an extension that is not
5
+ * installed, a read-only refusal. `@neon/tools/effect` keeps the tool span ok
6
+ * for it; any other `NeonClientError`, such as a malformed response, fails it.
7
+ *
8
+ * It keeps the name `NeonClientError`, which `@neon/effect` matches on and
9
+ * callers already see.
10
+ */
11
+ export declare class NeonToolCallerError extends NeonClientError {
12
+ constructor(message: string, options?: {
13
+ cause?: unknown;
14
+ });
15
+ }
16
+ //# sourceMappingURL=caller-error.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"caller-error.d.ts","sourceRoot":"","sources":["../../src/lib/caller-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1D"}
@@ -0,0 +1,18 @@
1
+ import { NeonClientError } from "@neon/sdk";
2
+ // src/lib/caller-error.ts
3
+ /**
4
+ * A `NeonClientError` a tool raises for a mistake in the call or in the
5
+ * caller's own resources: a missing page or table, an extension that is not
6
+ * installed, a read-only refusal. `@neon/tools/effect` keeps the tool span ok
7
+ * for it; any other `NeonClientError`, such as a malformed response, fails it.
8
+ *
9
+ * It keeps the name `NeonClientError`, which `@neon/effect` matches on and
10
+ * callers already see.
11
+ */
12
+ var NeonToolCallerError = class extends NeonClientError {
13
+ constructor(message, options) {
14
+ super(message, options);
15
+ this.name = "NeonClientError";
16
+ }
17
+ };
18
+ export { NeonToolCallerError };
@@ -1,7 +1,6 @@
1
1
  import { type NeonAuthWebhookConfig, type NeonClient } from "@neon/sdk";
2
2
  import * as z from "zod";
3
3
  import { type ToolClientOptions } from "../ergonomic/bind.js";
4
- export declare const REDACTED_SECRET = "***redacted***";
5
4
  export declare const getAuthConfigInputSchema: z.ZodObject<{
6
5
  project_id: z.ZodString;
7
6
  branch_id: z.ZodOptional<z.ZodString>;
@@ -1 +1 @@
1
- {"version":3,"file":"auth-config.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/auth-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAON,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAIzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,eAAO,MAAM,wBAAwB;;;kBASnC,CAAC;AA0GH,eAAO,MAAM,cAAc,GAC1B,MAAM,UAAU,CAAC,IAAI,CAAC,EACtB,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,EAChD,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyFpB,CAAC;AAgCF,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B1D,CAAC"}
1
+ {"version":3,"file":"auth-config.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/auth-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAON,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAIzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,wBAAwB;;;kBASnC,CAAC;AA0GH,eAAO,MAAM,cAAc,GAC1B,MAAM,UAAU,CAAC,IAAI,CAAC,EACtB,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,EAChD,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyFpB,CAAC;AAgCF,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmC1D,CAAC"}
@@ -5,7 +5,6 @@ import { NeonAuthIntegration } from "../../generated/output.gen.js";
5
5
  import * as z from "zod";
6
6
  import { NeonApiError } from "@neon/sdk";
7
7
  // src/lib/custom/auth-config.ts
8
- const REDACTED_SECRET = "***redacted***";
9
8
  const getAuthConfigInputSchema = z.strictObject({
10
9
  project_id: zGetNeonAuthPath.shape.project_id.describe(pathInputDescriptions.project_id),
11
10
  branch_id: zGetNeonAuthPath.shape.branch_id.describe(`${pathInputDescriptions.branch_id} Omit it for the project's default branch.`).optional()
@@ -25,7 +24,7 @@ const oauthProviderSettings = (provider) => ({
25
24
  id: provider.id,
26
25
  type: provider.type,
27
26
  client_id: provider.client_id ?? null,
28
- client_secret: provider.client_secret ? REDACTED_SECRET : null,
27
+ client_secret: provider.client_secret ?? null,
29
28
  ...provider.microsoft_tenant_id && { microsoft_tenant_id: provider.microsoft_tenant_id },
30
29
  ...provider.apple_team_id && { apple_team_id: provider.apple_team_id },
31
30
  ...provider.apple_key_id && { apple_key_id: provider.apple_key_id }
@@ -38,7 +37,7 @@ const emailProviderSettings = (data) => {
38
37
  host: data.host,
39
38
  port: data.port,
40
39
  username: data.username,
41
- password: REDACTED_SECRET,
40
+ password: data.password ?? null,
42
41
  sender_email: data.sender_email,
43
42
  sender_name: data.sender_name
44
43
  };
@@ -177,7 +176,7 @@ const getAuthConfigTool = (options) => bindTool(options, {
177
176
  operationId: "auth.getConfig",
178
177
  id: publishedId("auth.getConfig"),
179
178
  title: "Get Neon Auth configuration",
180
- description: "Returns a branch's Neon Auth integration and settings: trusted origins, localhost, email and password, OAuth and email providers, plugins, webhook, and logs export, with secrets redacted. Needs Neon Auth on the branch ({{auth.create}}).",
179
+ description: "Returns a branch's Neon Auth integration and settings: trusted origins, localhost, email and password, OAuth and email providers, plugins, webhook, and logs export. Needs Neon Auth on the branch ({{auth.create}}).",
181
180
  inputSchema: getAuthConfigInputSchema,
182
181
  outputSchema: authConfigOutputSchema,
183
182
  annotations: {
@@ -186,13 +185,21 @@ const getAuthConfigTool = (options) => bindTool(options, {
186
185
  idempotentHint: true,
187
186
  openWorldHint: false
188
187
  },
189
- requiresApproval: false,
188
+ requiresApproval: true,
190
189
  metadata: {
191
190
  method: "GET",
191
+ readOnlySafe: true,
192
+ secretOutputFields: [{
193
+ path: "$.oauth_providers[*].client_secret",
194
+ kind: "stored"
195
+ }, {
196
+ path: "$.email_provider.password",
197
+ kind: "stored"
198
+ }],
192
199
  path: "/projects/{project_id}/branches/{branch_id}/auth",
193
200
  stability: "stable",
194
201
  deprecated: false,
195
202
  tags: ["Auth"]
196
203
  }
197
204
  }, readAuthConfig);
198
- export { REDACTED_SECRET, getAuthConfigInputSchema, getAuthConfigTool, readAuthConfig };
205
+ export { getAuthConfigInputSchema, getAuthConfigTool, readAuthConfig };
@@ -1 +1 @@
1
- {"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/docs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAuB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3E,eAAO,MAAM,uBAAuB,8FACwD,CAAC;AAC7F,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAGxD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,gBAGlD,CAAC;AAmBF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;kBA2BhC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;kBAM5B,CAAC;AAiCH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC7B,QAAQ,cAAc,GAAG,SAAS,KAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBvB,CAAC;AAoCF,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DxD,CAAC;AAOF,eAAO,MAAM,UAAU,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;CA0CpD,CAAC"}
1
+ {"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAuB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3E,eAAO,MAAM,uBAAuB,8FACwD,CAAC;AAC7F,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAGxD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,gBAGlD,CAAC;AAmBF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;kBA2BhC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;kBAM5B,CAAC;AAiCH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC7B,QAAQ,cAAc,GAAG,SAAS,KAChC,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBvB,CAAC;AAoCF,eAAO,MAAM,cAAc,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DxD,CAAC;AAOF,eAAO,MAAM,UAAU,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;CA2CpD,CAAC"}
@@ -1,6 +1,6 @@
1
+ import { NeonToolCallerError } from "../caller-error.js";
1
2
  import { bindPublicTool, publishedId } from "../ergonomic/bind.js";
2
3
  import * as z from "zod";
3
- import { NeonClientError } from "@neon/sdk";
4
4
  // src/lib/custom/docs.ts
5
5
  const DEFAULT_SITE_SEARCH_URL = "https://br-frosty-cell-a5smzg39-assistant.compute.c-1.us-east-2.aws.neon.tech/site-search";
6
6
  const DEFAULT_DOCS_BASE_URL = "https://neon.com";
@@ -63,9 +63,9 @@ const searchDocsHeaders = (caller) => {
63
63
  return headers;
64
64
  };
65
65
  const validateDocSlug = (slug) => {
66
- if (slug.includes("..")) throw new NeonClientError("Invalid doc slug: path traversal (\"..\") is not allowed");
67
- if (slug.includes("://")) throw new NeonClientError("Invalid doc slug: absolute URLs are not allowed");
68
- if (slug.startsWith("/")) throw new NeonClientError("Invalid doc slug: slug must not start with \"/\"");
66
+ if (slug.includes("..")) throw new NeonToolCallerError("Invalid doc slug: path traversal (\"..\") is not allowed");
67
+ if (slug.includes("://")) throw new NeonToolCallerError("Invalid doc slug: absolute URLs are not allowed");
68
+ if (slug.startsWith("/")) throw new NeonToolCallerError("Invalid doc slug: slug must not start with \"/\"");
69
69
  };
70
70
  const searchDocsOutputSchema = z.looseObject({ hits: z.array(z.looseObject({
71
71
  title: z.string(),
@@ -90,6 +90,7 @@ const searchDocsTool = (options) => {
90
90
  requiresApproval: false,
91
91
  metadata: {
92
92
  method: "POST",
93
+ readOnlySafe: true,
93
94
  path: "/site-search",
94
95
  stability: "stable",
95
96
  deprecated: false,
@@ -109,7 +110,7 @@ const searchDocsTool = (options) => {
109
110
  } catch {
110
111
  throw new Error(`${UNEXPECTED_SEARCH_RESPONSE}: HTTP ${response.status}, body is not JSON`);
111
112
  }
112
- if (response.status === 400) throw new NeonClientError(upstreamError(body) ?? "Neon site search rejected the request");
113
+ if (response.status === 400) throw new NeonToolCallerError(upstreamError(body) ?? "Neon site search rejected the request");
113
114
  if (!response.ok) throw new Error(`Neon site search failed: HTTP ${response.status}`);
114
115
  const parsed = searchDocsResponseSchema.safeParse(body);
115
116
  if (!parsed.success) {
@@ -137,6 +138,7 @@ const getDocTool = (options) => {
137
138
  requiresApproval: false,
138
139
  metadata: {
139
140
  method: "GET",
141
+ readOnlySafe: true,
140
142
  path: "/{slug}.md",
141
143
  stability: "stable",
142
144
  deprecated: false,
@@ -147,7 +149,7 @@ const getDocTool = (options) => {
147
149
  const mdSlug = slug.endsWith(".md") ? slug : `${slug}.md`;
148
150
  const url = `${baseUrl}/${mdSlug}`;
149
151
  const response = await fetchImpl(url, { signal: upstreamSignal(context.signal) });
150
- if (response.status === 404) throw new NeonClientError(`Doc page not found: "${mdSlug}". Pass the slug of a docs search hit.`);
152
+ if (response.status === 404) throw new NeonToolCallerError(`Doc page not found: "${mdSlug}". Pass the slug of a docs search hit.`);
151
153
  if (!response.ok) throw new Error(`Failed to fetch doc page "${mdSlug}": ${response.status} ${response.statusText}`);
152
154
  return {
153
155
  url,
@@ -1 +1 @@
1
- {"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAClE,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAGpD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,eAAO,MAAM,uBAAuB;;kBASlC,CAAC;AAKH,eAAO,MAAM,gBAAgB,GAAI,SAAS,iBAAiB;;;;;;;;;;CA6D1D,CAAC"}
1
+ {"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAClE,eAAO,MAAM,uBAAuB,eAAe,CAAC;AAGpD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,eAAO,MAAM,uBAAuB;;kBASlC,CAAC;AAKH,eAAO,MAAM,gBAAgB,GAAI,SAAS,iBAAiB;;;;;;;;;;CA8D1D,CAAC"}
@@ -28,6 +28,7 @@ const sendFeedbackTool = (options) => {
28
28
  requiresApproval: true,
29
29
  metadata: {
30
30
  method: "POST",
31
+ readOnlySafe: true,
31
32
  path: "/",
32
33
  stability: "stable",
33
34
  deprecated: false,
@@ -1,4 +1,4 @@
1
- import { type NeonClient } from "@neon/sdk";
1
+ import type { NeonClient } from "@neon/sdk";
2
2
  import * as z from "zod";
3
3
  import { type ToolClientOptions } from "../ergonomic/bind.js";
4
4
  import type { NeonToolExecutionContext } from "../operation.js";
@@ -1 +1 @@
1
- {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAmC,MAAM,WAAW,CAAC;AAC7E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAQhE,eAAO,MAAM,wBAAwB;;kBAOnC,CAAC;AAkMH,eAAO,MAAM,aAAa,GACzB,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,IAAI,MAAM,EACV,SAAS,wBAAwB,EACjC,YAAY,MAAM,EAClB,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+DpB,CAAC;AAcF,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8B3D,CAAC"}
1
+ {"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAQhE,eAAO,MAAM,wBAAwB;;kBAOnC,CAAC;AAkMH,eAAO,MAAM,aAAa,GACzB,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,IAAI,MAAM,EACV,SAAS,wBAAwB,EACjC,YAAY,MAAM,EAClB,SAAS,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+DpB,CAAC;AAcF,eAAO,MAAM,iBAAiB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B3D,CAAC"}
@@ -1,8 +1,8 @@
1
+ import { NeonToolCallerError } from "../caller-error.js";
1
2
  import { bindTool, publishedId } from "../ergonomic/bind.js";
2
3
  import { consoleBaseUrl, isAccessRefusal } from "./resources.js";
3
4
  import { describeBranch } from "./sql/describe-branch.js";
4
5
  import * as z from "zod";
5
- import { NeonClientError } from "@neon/sdk";
6
6
  // src/lib/custom/fetch.ts
7
7
  const fetchResourceInputSchema = z.strictObject({ id: z.string().min(1).describe("An id from {{resources.search}}, such as project:<project_id>.") });
8
8
  /** The first page only; a list the API refuses is empty. */
@@ -113,7 +113,7 @@ ${JSON.stringify(endpoint, null, 2)}
113
113
  };
114
114
  const fetchSnapshot = async (neonClient, id, projectId, snapshotId, consoleUrl, signal) => {
115
115
  const snapshot = (await neonClient.snapshots.list({ projectId }, { signal })).find((candidate) => candidate.id === snapshotId);
116
- if (snapshot === void 0) throw new NeonClientError(`Snapshot ${snapshotId} not found in project ${projectId}`);
116
+ if (snapshot === void 0) throw new NeonToolCallerError(`Snapshot ${snapshotId} not found in project ${projectId}`);
117
117
  const text = `**Snapshot Details**
118
118
 
119
119
  - Name: ${snapshot.name}
@@ -132,7 +132,7 @@ ${JSON.stringify(snapshot, null, 2)}
132
132
  metadata: { snapshot }
133
133
  };
134
134
  };
135
- const invalidId = (id) => new NeonClientError(`Invalid ID format: "${id}". Expected format: org:*, project:*, branch:<project>/<branch>, endpoint:<project>/<endpoint>, or snapshot:<project>/<snapshot>`);
135
+ const invalidId = (id) => new NeonToolCallerError(`Invalid ID format: "${id}". Expected format: org:*, project:*, branch:<project>/<branch>, endpoint:<project>/<endpoint>, or snapshot:<project>/<snapshot>`);
136
136
  /** `<prefix><project>/<child>`, the form resources.search returns for project-scoped resources. */
137
137
  const projectScopedId = (id, prefix) => {
138
138
  const [projectId, childId, ...rest] = id.slice(prefix.length).split("/");
@@ -192,6 +192,7 @@ const fetchResourceTool = (options) => {
192
192
  requiresApproval: false,
193
193
  metadata: {
194
194
  method: "SQL",
195
+ readOnlySafe: true,
195
196
  path: "/projects",
196
197
  stability: "stable",
197
198
  deprecated: false,
@@ -1 +1 @@
1
- {"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/organizations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,4BAA4B;;kBAKvC,CAAC;AAEH,eAAO,MAAM,eAAe,GAC3B,QAAQ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACpC,OAAO,MAAM,YAOb,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B9D,CAAC"}
1
+ {"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/organizations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,4BAA4B;;kBAKvC,CAAC;AAEH,eAAO,MAAM,eAAe,GAC3B,QAAQ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACpC,OAAO,MAAM,YAOb,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B9D,CAAC"}
@@ -21,6 +21,7 @@ const userOrganizationsTool = (options) => bindTool(options, {
21
21
  requiresApproval: false,
22
22
  metadata: {
23
23
  method: "GET",
24
+ readOnlySafe: true,
24
25
  path: "/users/me/organizations",
25
26
  stability: "stable",
26
27
  deprecated: false,
@@ -1 +1 @@
1
- {"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/resources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,oBAAoB,qCAAqC,CAAC;AAGvE,eAAO,MAAM,0BAA0B;;kBAOrC,CAAC;AAQH,eAAO,MAAM,cAAc,GAAI,YAAY,MAAM,WACT,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAEF,CAAC;AAwIhD,eAAO,MAAM,mBAAmB,GAAI,SAAS,iBAAiB;;;;YAtJzD,MAAM;eACH,MAAM;aACR,MAAM;;;;;;;;;;;;;;;;CAuLX,CAAC"}
1
+ {"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/lib/custom/resources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,oBAAoB,qCAAqC,CAAC;AAGvE,eAAO,MAAM,0BAA0B;;kBAOrC,CAAC;AAQH,eAAO,MAAM,cAAc,GAAI,YAAY,MAAM,WACT,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAEF,CAAC;AAwIhD,eAAO,MAAM,mBAAmB,GAAI,SAAS,iBAAiB;;;;YAtJzD,MAAM;eACH,MAAM;aACR,MAAM;;;;;;;;;;;;;;;;CAwLX,CAAC"}
@@ -109,6 +109,7 @@ const searchResourcesTool = (options) => {
109
109
  requiresApproval: false,
110
110
  metadata: {
111
111
  method: "GET",
112
+ readOnlySafe: true,
112
113
  path: "/projects",
113
114
  stability: "stable",
114
115
  deprecated: false,
@@ -1,8 +1,12 @@
1
- import { type NeonClient } from "@neon/sdk";
1
+ import type { NeonClient } from "@neon/sdk";
2
2
  import * as z from "zod";
3
- import type { NeonToolExecutionContext, NeonToolMetadata } from "../../operation.js";
3
+ import type { NeonToolExecutionContext, NeonToolMetadataInput } from "../../operation.js";
4
4
  export declare const NEON_DEFAULT_DATABASE_NAME = "neondb";
5
- export declare const SQL_METADATA: NeonToolMetadata;
5
+ /**
6
+ * `readOnlySafe` for a tool that runs caller SQL means it runs one statement
7
+ * in its own `READ ONLY` transaction when `readOnly` is set.
8
+ */
9
+ export declare const sqlMetadata: (readOnlySafe: boolean) => NeonToolMetadataInput;
6
10
  export declare const DATABASE_NAME_DESCRIPTION = "Database name. Omit for neondb, else the first database.";
7
11
  export declare const projectIdField: z.ZodString;
8
12
  export declare const branchIdField: z.ZodOptional<z.ZodString>;
@@ -38,9 +42,4 @@ export declare const defaultDatabase: (neonClient: NeonClient<true>, ids: {
38
42
  */
39
43
  export declare const resolveConnection: (neonClient: NeonClient<true>, target: ConnectionTarget, context: NeonToolExecutionContext, signal?: AbortSignal) => Promise<ResolvedConnection>;
40
44
  export declare const sqlClient: (uri: string, signal?: AbortSignal) => import("@neondatabase/serverless").NeonQueryFunction<false, false>;
41
- /**
42
- * Caller SQL that shares one transaction can escape `READ ONLY` with `COMMIT`
43
- * or `SET TRANSACTION READ WRITE`, so these tools refuse instead.
44
- */
45
- export declare const refuseInReadOnly: (context: NeonToolExecutionContext) => void;
46
45
  //# sourceMappingURL=connection.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,WAAW,CAAC;AAE7D,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,KAAK,EACX,wBAAwB,EACxB,gBAAgB,EAChB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,0BAA0B,WAAW,CAAC;AAEnD,eAAO,MAAM,YAAY,EAAE,gBAM1B,CAAC;AAEF,eAAO,MAAM,yBAAyB,6DAAoF,CAAC;AAE3H,eAAO,MAAM,cAAc,aAEiB,CAAC;AAE7C,eAAO,MAAM,aAAa,4BAKxB,CAAC;AAEH,eAAO,MAAM,iBAAiB,4BAGO,CAAC;AAEtC,eAAO,MAAM,aAAa,4BAG4C,CAAC;AAEvE,eAAO,MAAM,sBAAsB,mEAC8B,CAAC;AAElE,eAAO,MAAM,cAAc,4BAGO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,GAC3B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,KAAK;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC5C,SAAS,WAAW,0CAcpB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC7B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,QAAQ,gBAAgB,EACxB,SAAS,wBAAwB,EACjC,SAAS,WAAW,KAClB,OAAO,CAAC,kBAAkB,CAyD5B,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,SAAS,WAAW,uEACS,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,wBAAwB,SAMjE,CAAC"}
1
+ {"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,OAAO,KAAK,EACX,wBAAwB,EACxB,qBAAqB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,eAAO,MAAM,0BAA0B,WAAW,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,cAAc,OAAO,KAAG,qBAOlD,CAAC;AAEH,eAAO,MAAM,yBAAyB,6DAAoF,CAAC;AAE3H,eAAO,MAAM,cAAc,aAEiB,CAAC;AAE7C,eAAO,MAAM,aAAa,4BAKxB,CAAC;AAEH,eAAO,MAAM,iBAAiB,4BAGO,CAAC;AAEtC,eAAO,MAAM,aAAa,4BAG4C,CAAC;AAEvE,eAAO,MAAM,sBAAsB,mEAC8B,CAAC;AAElE,eAAO,MAAM,cAAc,4BAGO,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qEAAqE;AACrE,eAAO,MAAM,eAAe,GAC3B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,KAAK;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC5C,SAAS,WAAW,0CAgBpB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC7B,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,QAAQ,gBAAgB,EACxB,SAAS,wBAAwB,EACjC,SAAS,WAAW,KAClB,OAAO,CAAC,kBAAkB,CAyD5B,CAAC;AAEF,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,EAAE,SAAS,WAAW,uEACS,CAAC"}
@@ -1,16 +1,21 @@
1
1
  import { pathInputDescriptions } from "../../../descriptions.gen.js";
2
+ import { NeonToolCallerError } from "../../caller-error.js";
2
3
  import { neon } from "@neondatabase/serverless";
3
4
  import * as z from "zod";
4
- import { NeonClientError } from "@neon/sdk";
5
5
  // src/lib/custom/sql/connection.ts
6
6
  const NEON_DEFAULT_DATABASE_NAME = "neondb";
7
- const SQL_METADATA = {
7
+ /**
8
+ * `readOnlySafe` for a tool that runs caller SQL means it runs one statement
9
+ * in its own `READ ONLY` transaction when `readOnly` is set.
10
+ */
11
+ const sqlMetadata = (readOnlySafe) => ({
8
12
  method: "SQL",
9
13
  path: "/projects/{project_id}/connection_uri",
10
14
  stability: "stable",
11
15
  deprecated: false,
12
- tags: ["SQL"]
13
- };
16
+ tags: ["SQL"],
17
+ readOnlySafe
18
+ });
14
19
  const DATABASE_NAME_DESCRIPTION = `Database name. Omit for ${NEON_DEFAULT_DATABASE_NAME}, else the first database.`;
15
20
  const projectIdField = z.string().describe(pathInputDescriptions.project_id);
16
21
  const branchIdField = z.string().optional().describe(`${pathInputDescriptions.branch_id} Omit it for the default branch.`);
@@ -22,7 +27,7 @@ const computeIdField = z.string().optional().describe(COMPUTE_ID_DESCRIPTION);
22
27
  const defaultDatabase = async (neonClient, ids, signal) => {
23
28
  const databases = await neonClient.postgres.databases.list(ids, { signal });
24
29
  const first = databases[0];
25
- if (first === void 0) throw new NeonClientError("No databases found in your project branch");
30
+ if (first === void 0) throw new NeonToolCallerError("No databases found in your project branch");
26
31
  return databases.find((database) => database.name === "neondb") ?? first;
27
32
  };
28
33
  /**
@@ -34,7 +39,7 @@ const resolveConnection = async (neonClient, target, context, signal) => {
34
39
  let roleName = target.role_name;
35
40
  const pinnedRole = context.postgresRole;
36
41
  if (pinnedRole !== void 0) {
37
- if (roleName !== void 0 && roleName !== pinnedRole) throw new NeonClientError(`This connection is pinned to Postgres role "${pinnedRole}"; role_name "${roleName}" is not allowed.`);
42
+ if (roleName !== void 0 && roleName !== pinnedRole) throw new NeonToolCallerError(`This connection is pinned to Postgres role "${pinnedRole}"; role_name "${roleName}" is not allowed.`);
38
43
  roleName = pinnedRole;
39
44
  }
40
45
  const branchId = target.branch_id ?? (await neonClient.branches.getDefault({ projectId }, { signal })).id;
@@ -68,11 +73,4 @@ const resolveConnection = async (neonClient, target, context, signal) => {
68
73
  };
69
74
  };
70
75
  const sqlClient = (uri, signal) => neon(uri, signal === void 0 ? {} : { fetchOptions: { signal } });
71
- /**
72
- * Caller SQL that shares one transaction can escape `READ ONLY` with `COMMIT`
73
- * or `SET TRANSACTION READ WRITE`, so these tools refuse instead.
74
- */
75
- const refuseInReadOnly = (context) => {
76
- if (context.readOnly === true) throw new NeonClientError("This tool is unavailable in read-only mode because it runs caller SQL that can leave a read-only transaction.");
77
- };
78
- export { COMPUTE_ID_DESCRIPTION, DATABASE_NAME_DESCRIPTION, NEON_DEFAULT_DATABASE_NAME, SQL_METADATA, branchIdField, computeIdField, databaseNameField, defaultDatabase, projectIdField, refuseInReadOnly, resolveConnection, roleNameField, sqlClient };
76
+ export { COMPUTE_ID_DESCRIPTION, DATABASE_NAME_DESCRIPTION, NEON_DEFAULT_DATABASE_NAME, branchIdField, computeIdField, databaseNameField, defaultDatabase, projectIdField, resolveConnection, roleNameField, sqlClient, sqlMetadata };
@@ -1,6 +1,6 @@
1
1
  import { pathInputDescriptions } from "../../../descriptions.gen.js";
2
2
  import { bindTool, publishedId } from "../../ergonomic/bind.js";
3
- import { SQL_METADATA, databaseNameField, projectIdField, resolveConnection, sqlClient } from "./connection.js";
3
+ import { databaseNameField, projectIdField, resolveConnection, sqlClient, sqlMetadata } from "./connection.js";
4
4
  import { sqlReadAnnotations } from "./schema.js";
5
5
  import { Branch } from "../../../generated/output.gen.js";
6
6
  import { consoleBaseUrl } from "../resources.js";
@@ -158,7 +158,7 @@ const describeBranchTool = (options) => {
158
158
  outputSchema: describeBranchOutputSchema,
159
159
  annotations: sqlReadAnnotations,
160
160
  requiresApproval: false,
161
- metadata: SQL_METADATA
161
+ metadata: sqlMetadata(true)
162
162
  }, (neonClient, input, signal, context) => describeBranch(neonClient, input, context, consoleUrl, signal));
163
163
  };
164
164
  export { branchConsoleUrl, describeBranch, describeBranchInputSchema, describeBranchTool };
@@ -1 +1 @@
1
- {"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/inspect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EAKN,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO;CAKhE;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;kBAsBrC,CAAC;AAuFH,eAAO,MAAM,mBAAmB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4G5D,CAAC"}
1
+ {"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../../../../src/lib/custom/sql/inspect/inspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,4BAA4B,CAAC;AAUpC,OAAO,EAKN,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAItB;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO;CAKhE;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;kBAsBrC,CAAC;AAuFH,eAAO,MAAM,mBAAmB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4G5D,CAAC"}
@@ -1,12 +1,12 @@
1
+ import { NeonToolCallerError } from "../../../caller-error.js";
1
2
  import { INSPECT_CHECKS, INSPECT_MAX_LIMIT, INSPECT_QUERIES } from "./queries.js";
2
3
  import { assembleInspectReport } from "./report.js";
3
4
  import { bindTool, publishedId } from "../../../ergonomic/bind.js";
4
- import { SQL_METADATA, branchIdField, computeIdField, projectIdField, resolveConnection, sqlClient } from "../connection.js";
5
+ import { branchIdField, computeIdField, projectIdField, resolveConnection, sqlClient, sqlMetadata } from "../connection.js";
5
6
  import { sqlReadAnnotations } from "../schema.js";
6
7
  import { formatInspectQueryError, selectInspectTargets } from "./targets.js";
7
8
  import { NeonDbError } from "@neondatabase/serverless";
8
9
  import * as z from "zod";
9
- import { NeonClientError } from "@neon/sdk";
10
10
  // src/lib/custom/sql/inspect/inspect.ts
11
11
  /**
12
12
  * Postgres rejected one of the package's own diagnostic queries. That is a bug
@@ -49,7 +49,7 @@ const runInspectOnDatabase = async (check, uri, databaseName, signal) => {
49
49
  const sql = sqlClient(uri, signal);
50
50
  if (query.requiresExtension) {
51
51
  const extension = query.requiresExtension;
52
- if ((await runDiagnostic(check, () => sql.query("SELECT 1 FROM pg_extension WHERE extname = $1", [extension]))).length === 0) throw new NeonClientError(`The "${check}" check needs the "${extension}" extension, which is not installed on database "${databaseName}". Installing it writes to the user's database, so ask the user first, then run \`CREATE EXTENSION IF NOT EXISTS ${extension};\`.`);
52
+ if ((await runDiagnostic(check, () => sql.query("SELECT 1 FROM pg_extension WHERE extname = $1", [extension]))).length === 0) throw new NeonToolCallerError(`The "${check}" check needs the "${extension}" extension, which is not installed on database "${databaseName}". Installing it writes to the user's database, so ask the user first, then run \`CREATE EXTENSION IF NOT EXISTS ${extension};\`.`);
53
53
  }
54
54
  const [rows] = await runDiagnostic(check, () => sql.transaction([sql.query(query.sql)], { readOnly: true }));
55
55
  return rows;
@@ -88,7 +88,7 @@ const inspectDatabaseTool = (options) => bindTool(options, {
88
88
  outputSchema: inspectDatabaseOutputSchema,
89
89
  annotations: sqlReadAnnotations,
90
90
  requiresApproval: false,
91
- metadata: SQL_METADATA
91
+ metadata: sqlMetadata(true)
92
92
  }, async (neonClient, input, signal, context) => {
93
93
  const { check, database_name: databaseName, limit } = input;
94
94
  const query = INSPECT_QUERIES[check];
@@ -106,7 +106,7 @@ const inspectDatabaseTool = (options) => bindTool(options, {
106
106
  projectId,
107
107
  branchId
108
108
  }, { signal })).map((database) => database.name);
109
- if (branchDatabases.length === 0) throw new NeonClientError("No databases found in your project branch");
109
+ if (branchDatabases.length === 0) throw new NeonToolCallerError("No databases found in your project branch");
110
110
  branchDatabaseCount = branchDatabases.length;
111
111
  selection = selectInspectTargets({
112
112
  branchDatabases,
@@ -1,4 +1,4 @@
1
- import { NeonClientError } from "@neon/sdk";
1
+ import { NeonToolCallerError } from "../../../caller-error.js";
2
2
  // src/lib/custom/sql/inspect/targets.ts
3
3
  /**
4
4
  * Keep the database column on one-database branches so adding another database
@@ -7,13 +7,13 @@ import { NeonClientError } from "@neon/sdk";
7
7
  */
8
8
  const selectInspectTargets = (input) => {
9
9
  if (input.databaseName !== void 0) {
10
- if (input.databaseName === "") throw new NeonClientError("database_name cannot be empty. Omit it to cover every database.");
10
+ if (input.databaseName === "") throw new NeonToolCallerError("database_name cannot be empty. Omit it to cover every database.");
11
11
  return {
12
12
  databases: [input.databaseName],
13
13
  includeDatabaseColumn: false
14
14
  };
15
15
  }
16
- if (input.branchDatabases.length === 0) throw new NeonClientError("No databases found for the branch");
16
+ if (input.branchDatabases.length === 0) throw new NeonToolCallerError("No databases found for the branch");
17
17
  if (input.scope === "compute") return {
18
18
  databases: [input.branchDatabases[0]],
19
19
  includeDatabaseColumn: false
@@ -1 +1 @@
1
- {"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAmB,MAAM,WAAW,CAAC;AAE1E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AAcjC,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,MAAM,EACxB,CAAC;AA8BhC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAU,CAAC,EAC1C,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,WAAW,MAAM,EACjB,MAAM,MAAM,GAAG,SAAS,EACxB,QAAQ,WAAW,GAAG,SAAS,EAC/B,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,KACjC,OAAO,CAAC,CAAC,CAgCX,CAAC;AAMF,eAAO,MAAM,2BAA2B;;;;kBAQtC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;kBAuBvC,CAAC;AAyBH,eAAO,MAAM,oBAAoB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0E7D,CAAC;AAcH,eAAO,MAAM,qBAAqB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqD9D,CAAC"}
1
+ {"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAmB,MAAM,WAAW,CAAC;AAE1E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAGN,KAAK,iBAAiB,EACtB,MAAM,yBAAyB,CAAC;AAajC,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,GAAI,KAAK,MAAM,KAAG,MAAM,EACxB,CAAC;AA8BhC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAU,CAAC,EAC1C,YAAY,UAAU,CAAC,IAAI,CAAC,EAC5B,WAAW,MAAM,EACjB,MAAM,MAAM,GAAG,SAAS,EACxB,QAAQ,WAAW,GAAG,SAAS,EAC/B,KAAK,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,KACjC,OAAO,CAAC,CAAC,CAgCX,CAAC;AAMF,eAAO,MAAM,2BAA2B;;;;kBAQtC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;kBAuBvC,CAAC;AAyBH,eAAO,MAAM,oBAAoB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyE7D,CAAC;AAcH,eAAO,MAAM,qBAAqB,GAAI,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD9D,CAAC"}
@@ -1,5 +1,5 @@
1
1
  import { bindTool, publishedId } from "../../ergonomic/bind.js";
2
- import { DATABASE_NAME_DESCRIPTION, SQL_METADATA, defaultDatabase, projectIdField, refuseInReadOnly } from "./connection.js";
2
+ import { DATABASE_NAME_DESCRIPTION, defaultDatabase, projectIdField, sqlMetadata } from "./connection.js";
3
3
  import { runTransaction, sqlRowsOutputSchema, sqlWriteAnnotations } from "./run.js";
4
4
  import * as z from "zod";
5
5
  import { NeonClientError } from "@neon/sdk";
@@ -93,9 +93,8 @@ const prepareMigrationTool = (options) => bindTool(options, {
93
93
  openWorldHint: false
94
94
  },
95
95
  requiresApproval: true,
96
- metadata: SQL_METADATA
96
+ metadata: sqlMetadata(false)
97
97
  }, async (neonClient, input, signal, context) => {
98
- refuseInReadOnly(context);
99
98
  const projectId = input.project_id;
100
99
  return withTemporaryBranch(neonClient, projectId, migrationBranchName(), signal, async (branch) => {
101
100
  const parentBranchId = branch.parent_id;
@@ -142,9 +141,8 @@ const completeMigrationTool = (options) => bindTool(options, {
142
141
  outputSchema: completeMigrationOutputSchema,
143
142
  annotations: sqlWriteAnnotations,
144
143
  requiresApproval: true,
145
- metadata: SQL_METADATA
144
+ metadata: sqlMetadata(false)
146
145
  }, async (neonClient, input, signal, context) => {
147
- refuseInReadOnly(context);
148
146
  const migrationResult = input.apply_changes ? await runTransaction(neonClient, {
149
147
  project_id: input.project_id,
150
148
  branch_id: input.parent_branch_id,
@@ -22,6 +22,8 @@ export interface PlanTable {
22
22
  }
23
23
  /** Every relation an `EXPLAIN (FORMAT JSON)` result scans. */
24
24
  export declare const extractTablesFromPlan: (plan: unknown) => PlanTable[];
25
+ /** Whether `rows` hold the JSON plan document `EXPLAIN (FORMAT JSON)` returns. */
26
+ export declare const hasPlanDocument: (rows: unknown) => boolean;
25
27
  /**
26
28
  * Query-level totals from the rows `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`
27
29
  * returns: one row whose `QUERY PLAN` column holds the plan document. They come
@@ -1 +1 @@
1
- {"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/plan.ts"],"names":[],"mappings":"AAAA,UAAU,aAAa;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACZ,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;KACrB,CAAC;CACF;AAUD,MAAM,WAAW,SAAS;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACnB;AAKD,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,KAAG,SAAS,EAqB9D,CAAC;AAYF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,OAAO,KAAG,YAkBvD,CAAC"}
1
+ {"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/lib/custom/sql/plan.ts"],"names":[],"mappings":"AAAA,UAAU,aAAa;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE;QACZ,MAAM,EAAE,aAAa,CAAC;QACtB,KAAK,EAAE,aAAa,CAAC;KACrB,CAAC;CACF;AAUD,MAAM,WAAW,SAAS;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACnB;AAKD,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,GAAI,MAAM,OAAO,KAAG,SAAS,EAqB9D,CAAC;AAsBF,kFAAkF;AAClF,eAAO,MAAM,eAAe,GAAI,MAAM,OAAO,KAAG,OAG/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,MAAM,OAAO,KAAG,YAgBvD,CAAC"}
@@ -34,6 +34,21 @@ const buffers = (node, prefix) => ({
34
34
  written: numberAt(node, `${prefix} Written Blocks`),
35
35
  dirtied: numberAt(node, `${prefix} Dirtied Blocks`)
36
36
  });
37
+ const planDocument = (rows) => {
38
+ const firstRow = Array.isArray(rows) ? rows[0] : void 0;
39
+ const documents = isRecord(firstRow) ? firstRow["QUERY PLAN"] : void 0;
40
+ const document = Array.isArray(documents) ? documents[0] : void 0;
41
+ const root = isRecord(document) ? document.Plan : void 0;
42
+ return isRecord(document) && isRecord(root) ? {
43
+ document,
44
+ root
45
+ } : void 0;
46
+ };
47
+ /** Whether `rows` hold the JSON plan document `EXPLAIN (FORMAT JSON)` returns. */
48
+ const hasPlanDocument = (rows) => {
49
+ const nodeType = planDocument(rows)?.root["Node Type"];
50
+ return typeof nodeType === "string" && nodeType !== "";
51
+ };
37
52
  /**
38
53
  * Query-level totals from the rows `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)`
39
54
  * returns: one row whose `QUERY PLAN` column holds the plan document. They come
@@ -41,11 +56,9 @@ const buffers = (node, prefix) => ({
41
56
  * counters already include its children.
42
57
  */
43
58
  const extractExecutionMetrics = (rows) => {
44
- const firstRow = Array.isArray(rows) ? rows[0] : void 0;
45
- const documents = isRecord(firstRow) ? firstRow["QUERY PLAN"] : void 0;
46
- const document = Array.isArray(documents) ? documents[0] : void 0;
47
- const root = isRecord(document) ? document.Plan : void 0;
48
- if (!isRecord(document) || !isRecord(root)) throw new Error("EXPLAIN returned no JSON plan document");
59
+ const plan = planDocument(rows);
60
+ if (plan === void 0) throw new Error("EXPLAIN returned no JSON plan document");
61
+ const { document, root } = plan;
49
62
  return {
50
63
  executionTime: numberAt(document, "Execution Time"),
51
64
  planningTime: numberAt(document, "Planning Time"),
@@ -57,4 +70,4 @@ const extractExecutionMetrics = (rows) => {
57
70
  }
58
71
  };
59
72
  };
60
- export { extractExecutionMetrics, extractTablesFromPlan };
73
+ export { extractExecutionMetrics, extractTablesFromPlan, hasPlanDocument };