@ductape/cli 0.4.6 → 0.5.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.
@@ -0,0 +1,317 @@
1
+ import fs from 'node:fs';
2
+ export const CLOUD_PROVIDERS = ['aws', 'gcp', 'azure', 'mongodb_atlas', 'neo4j_aura'];
3
+ export const realIo = { readFile: (file) => fs.readFileSync(file, 'utf8'), env: process.env };
4
+ const ROLE_ARN = /^arn:aws[a-z-]*:iam::\d{12}:role\/[\w+=,.@/-]+$/;
5
+ const RUNTIME_ACCOUNT = /^[A-Za-z0-9._-]+@[A-Za-z0-9.-]+\.iam\.gserviceaccount\.com$|^\d+-compute@developer\.gserviceaccount\.com$/;
6
+ /** A secret is only ever read from a file or an environment variable, so it never lands in shell history or a process list. */
7
+ function secretFromEnv(variable, flag, io) {
8
+ if (variable === undefined)
9
+ return undefined;
10
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable))
11
+ throw new Error(`${flag} takes the NAME of an environment variable, not the secret itself`);
12
+ const value = io.env[variable];
13
+ if (!value)
14
+ throw new Error(`The environment variable ${variable} named by ${flag} is not set or is empty`);
15
+ return value;
16
+ }
17
+ function readServiceAccount(file, io) {
18
+ let raw;
19
+ try {
20
+ raw = io.readFile(file);
21
+ }
22
+ catch (error) {
23
+ throw new Error(`Cannot read the service account key file ${file}: ${error instanceof Error ? error.message : String(error)}`);
24
+ }
25
+ let parsed;
26
+ try {
27
+ parsed = JSON.parse(raw);
28
+ }
29
+ catch {
30
+ throw new Error(`${file} is not valid JSON. It should be the key file downloaded for the service account.`);
31
+ }
32
+ for (const field of ['type', 'client_email', 'private_key', 'project_id']) {
33
+ if (typeof parsed[field] !== 'string' || !parsed[field])
34
+ throw new Error(`${file} is not a service account key: it has no "${field}"`);
35
+ }
36
+ if (parsed.type !== 'service_account')
37
+ throw new Error(`${file} is a "${String(parsed.type)}" credential, but a service account key is needed`);
38
+ return parsed;
39
+ }
40
+ const compact = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
41
+ /**
42
+ * Builds the request body for `ductape cloud connections <verb>` from flags, on top of any body read from a file. Flags win.
43
+ * Nothing secret is accepted as a flag value.
44
+ */
45
+ export function buildConnectionBody(verb, flags, base = {}, io = realIo) {
46
+ const body = { ...base };
47
+ const v = verb.toLowerCase();
48
+ if (v === 'create') {
49
+ if (flags.provider !== undefined)
50
+ body.provider = flags.provider;
51
+ if (flags.name !== undefined)
52
+ body.name = flags.name;
53
+ if (flags.tag !== undefined)
54
+ body.tag = flags.tag;
55
+ if (typeof body.tag === 'string') {
56
+ // The platform stores tags as lowercase letters, digits and underscores. Saying so now avoids a tag that cannot be found later.
57
+ const stored = body.tag.toLowerCase().trim().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
58
+ if (!stored)
59
+ throw new Error('--tag needs at least one letter or digit');
60
+ if (stored !== body.tag)
61
+ throw new Error(`--tag "${body.tag}" would be stored as "${stored}". Use --tag ${stored}, so the tag you type later matches.`);
62
+ }
63
+ if (flags.description !== undefined)
64
+ body.description = flags.description;
65
+ if (flags.authMode !== undefined)
66
+ body.auth_mode = flags.authMode;
67
+ if (!CLOUD_PROVIDERS.includes(body.provider)) {
68
+ throw new Error(`--provider is required and must be one of: ${CLOUD_PROVIDERS.join(', ')}`);
69
+ }
70
+ if (typeof body.name !== 'string' || !body.name.trim())
71
+ throw new Error('--name is required');
72
+ let scopes = Array.isArray(body.scopes) ? body.scopes : undefined;
73
+ if (flags.scopes !== undefined)
74
+ scopes = flags.scopes.split(',').map((s) => s.trim()).filter(Boolean);
75
+ if (flags.deploy) {
76
+ if (body.provider !== 'gcp')
77
+ throw new Error('--deploy is only available for GCP connections today; AWS and Azure deploy adapters are not built yet');
78
+ scopes = [...new Set([...(scopes ?? []), 'deploy'])];
79
+ }
80
+ if (scopes !== undefined) {
81
+ if (scopes.length === 0)
82
+ throw new Error('--scopes needs at least one scope');
83
+ body.scopes = scopes;
84
+ }
85
+ return body;
86
+ }
87
+ if (v === 'complete') {
88
+ if (flags.projectId !== undefined)
89
+ body.project_id = flags.projectId;
90
+ if (flags.runtimeServiceAccount !== undefined) {
91
+ if (!RUNTIME_ACCOUNT.test(flags.runtimeServiceAccount))
92
+ throw new Error('--runtime-service-account must be a service account email such as app-runtime@my-project.iam.gserviceaccount.com');
93
+ body.runtime_service_account = flags.runtimeServiceAccount;
94
+ }
95
+ if (flags.serviceAccountFile !== undefined) {
96
+ const key = readServiceAccount(flags.serviceAccountFile, io);
97
+ if (flags.projectId !== undefined && flags.projectId !== key.project_id) {
98
+ throw new Error(`--project-id ${flags.projectId} does not match the key file's project ${String(key.project_id)}. A key only works in its own project.`);
99
+ }
100
+ body.project_id = flags.projectId ?? key.project_id;
101
+ body.service_account_json = key;
102
+ }
103
+ if (flags.roleArn !== undefined) {
104
+ if (!ROLE_ARN.test(flags.roleArn))
105
+ throw new Error('--role-arn must look like arn:aws:iam::123456789012:role/ductape-access');
106
+ body.role_arn = flags.roleArn;
107
+ }
108
+ if (flags.tenantId !== undefined)
109
+ body.tenant_id = flags.tenantId;
110
+ if (flags.subscriptionId !== undefined)
111
+ body.subscription_id = flags.subscriptionId;
112
+ if (flags.clientId !== undefined)
113
+ body.client_id = flags.clientId;
114
+ if (flags.defaultLocation !== undefined)
115
+ body.default_location = flags.defaultLocation;
116
+ const azureSecret = secretFromEnv(flags.clientSecretEnv, '--client-secret-env', io);
117
+ if (azureSecret !== undefined)
118
+ body.client_secret = azureSecret;
119
+ if (flags.atlasPublicKey !== undefined)
120
+ body.atlas_public_key = flags.atlasPublicKey;
121
+ const atlasSecret = secretFromEnv(flags.atlasPrivateKeyEnv, '--atlas-private-key-env', io);
122
+ if (atlasSecret !== undefined)
123
+ body.atlas_private_key = atlasSecret;
124
+ if (flags.auraClientId !== undefined)
125
+ body.aura_client_id = flags.auraClientId;
126
+ if (flags.auraInstanceId !== undefined)
127
+ body.aura_instance_id = flags.auraInstanceId;
128
+ const auraSecret = secretFromEnv(flags.auraClientSecretEnv, '--aura-client-secret-env', io);
129
+ if (auraSecret !== undefined)
130
+ body.aura_client_secret = auraSecret;
131
+ if (Object.keys(compact(body)).length === 0)
132
+ throw new Error('Nothing to complete with. Give the provider\'s details as flags (see `ductape cloud connections guide`) or -f <file>.');
133
+ return body;
134
+ }
135
+ if (v === 'update') {
136
+ if (flags.name !== undefined)
137
+ body.display_name = flags.name;
138
+ if (flags.description !== undefined)
139
+ body.description = flags.description;
140
+ if (flags.scopes !== undefined)
141
+ body.scopes = flags.scopes.split(',').map((s) => s.trim()).filter(Boolean);
142
+ return body;
143
+ }
144
+ return body;
145
+ }
146
+ const SECRETS_RULE = 'Credentials stay out of chat, shell arguments and source control. Key files are read from disk and secrets from environment variables, so an assistant guiding you never needs to see them. Do not paste a key or secret into a conversation.';
147
+ export const GCP_DEPLOY_ROLE_LIST = [
148
+ { role: 'roles/run.admin', for: 'create and update Cloud Run services, move traffic, and let the service account call them' },
149
+ { role: 'roles/cloudbuild.builds.editor', for: 'start source builds and read their result' },
150
+ { role: 'roles/artifactregistry.admin', for: 'create the image repository and read built images' },
151
+ { role: 'roles/secretmanager.admin', for: 'create each deployment\'s signing-key secret and let the runtime account read it' },
152
+ { role: 'roles/storage.admin', for: 'create the source staging bucket and read uploaded source' },
153
+ { role: 'roles/iam.serviceAccountUser', for: 'deploy a service that runs as the runtime service account' },
154
+ { role: 'roles/browser', for: 'read the project to find its number' },
155
+ ];
156
+ /** Everything a deploy through a GCP connection leaves in the customer's project. All of it is labelled as Ductape's. */
157
+ export const GCP_DEPLOY_CREATES = [
158
+ 'A Cloud Storage bucket named <PROJECT_ID>-ductape-source, where your source is uploaded to be built',
159
+ 'An Artifact Registry repository named "ductape" in the region you build in, holding the built images',
160
+ 'One Cloud Build per build',
161
+ 'One Cloud Run service per deployed version of a function or service (private: callers need an identity token)',
162
+ 'One Secret Manager secret per deployed function, holding its signing key (a service gets none)',
163
+ ];
164
+ export const GCP_DEPLOY_SAFETY = 'Ductape only adds resources it labels as its own (ductape_managed), never changes or reuses one it did not create, and never deletes anything, including what it created. Removing deployed resources is always your own action. Use a dedicated project if you can, so what Ductape adds is easy to see.';
165
+ export const GCP_DEPLOY_TROUBLESHOOTING = [
166
+ { problem: '"<API> has not been used in project <PROJECT_ID> before or it is disabled"', fix: 'Enable that API (step 1), wait a minute or two for it to take effect, and try again.' },
167
+ { problem: 'Validation lists missing permissions and the roles that grant them', fix: 'Grant exactly those roles to the Ductape service account on the project (step 3) and validate again. Role changes can take a minute to apply.' },
168
+ { problem: '"caller does not have permission to act as service account ..." when a build or deploy starts', fix: 'Grant roles/iam.serviceAccountUser to the Ductape service account on the project. Cloud Build and Cloud Run run as a service account, and the Ductape account must be allowed to act as it.' },
169
+ { problem: 'A role you granted is reported missing again, or one that was there before has gone', fix: 'Some IAM screens replace the roles on an account instead of adding to them. Open the Ductape service account in IAM and check that it holds all seven roles together (roles/run.admin, roles/cloudbuild.builds.editor, roles/artifactregistry.admin, roles/secretmanager.admin, roles/storage.admin, roles/iam.serviceAccountUser, roles/browser), then validate again.' },
170
+ { problem: 'A build fails with a permission error', fix: 'Builds run as Cloud Build\'s own service account, shown in the build log. Give that account roles/artifactregistry.writer, roles/logging.logWriter and roles/storage.objectViewer.' },
171
+ { problem: 'The connection says it was not created for deploys', fix: 'Create it with --deploy so it carries the deploy scope. A connection made for resources only cannot build or deploy.' },
172
+ { problem: 'A deployed service answers 401 or 403 when you open it in a browser', fix: 'That is intended. Services are private; Ductape calls them with an identity token. Making one public is a separate, approved step that does not exist yet.' },
173
+ ];
174
+ export const GCP_DEPLOY_APIS = [
175
+ 'run.googleapis.com', 'cloudbuild.googleapis.com', 'artifactregistry.googleapis.com', 'secretmanager.googleapis.com',
176
+ 'storage.googleapis.com', 'cloudresourcemanager.googleapis.com', 'iam.googleapis.com',
177
+ ];
178
+ export function connectionGuide(providerInput, purposeInput = 'resources') {
179
+ if (!CLOUD_PROVIDERS.includes(providerInput))
180
+ throw new Error(`--provider must be one of: ${CLOUD_PROVIDERS.join(', ')}`);
181
+ if (purposeInput !== 'resources' && purposeInput !== 'deploy')
182
+ throw new Error('--purpose must be "resources" or "deploy"');
183
+ const provider = providerInput;
184
+ const purpose = purposeInput;
185
+ const base = { provider, purpose, secrets: SECRETS_RULE };
186
+ if (purpose === 'deploy' && provider !== 'gcp') {
187
+ return {
188
+ ...base, supported: false,
189
+ summary: `Deploying code through a ${provider} connection is not available yet. Only GCP (Cloud Run and Cloud Build) has a deploy adapter. A ${provider} connection can still manage resources: ask for the "resources" guide.`,
190
+ steps: [],
191
+ };
192
+ }
193
+ if (provider === 'gcp') {
194
+ const deploy = purpose === 'deploy';
195
+ const apis = deploy ? GCP_DEPLOY_APIS : ['storage.googleapis.com', 'sqladmin.googleapis.com', 'pubsub.googleapis.com', 'spanner.googleapis.com'];
196
+ const roles = deploy ? GCP_DEPLOY_ROLE_LIST : [];
197
+ const bind = (role) => `gcloud projects add-iam-policy-binding <PROJECT_ID> --member "serviceAccount:ductape@<PROJECT_ID>.iam.gserviceaccount.com" --role ${role}`;
198
+ return {
199
+ ...base, supported: true,
200
+ summary: deploy
201
+ ? 'Lets Ductape deploy to Cloud Run and build source in your own GCP project, using a service account you create and control.'
202
+ : 'Lets Ductape manage storage, databases, brokers, graphs and vectors in your GCP project, using a service account you create and control.',
203
+ steps: [
204
+ {
205
+ step: 1, who: 'you', title: 'Enable the APIs', commands: [`gcloud services enable ${apis.join(' ')} --project <PROJECT_ID>`],
206
+ ...(deploy ? {
207
+ notes: ['An API that is off makes the deploy fail with "has not been used in project ... or it is disabled". It can take a minute or two to switch on.'],
208
+ links: apis.map((api) => ({ label: api, url: `https://console.cloud.google.com/apis/library/${api}?project=<PROJECT_ID>` })),
209
+ } : {}),
210
+ },
211
+ { step: 2, who: 'you', title: 'Create a service account for Ductape', commands: ['gcloud iam service-accounts create ductape --project <PROJECT_ID> --display-name "Ductape"'] },
212
+ deploy
213
+ ? {
214
+ step: 3, who: 'you', title: 'Grant the roles Ductape Deploy uses', commands: roles.map((r) => bind(r.role)),
215
+ notes: [...roles.map((r) => `${r.role}: ${r.for}`), 'The account needs all of them at once. Each gcloud command adds one; in the console, add every role in one go and then check the account lists all seven, because some screens replace the roles an account already has.'],
216
+ links: [{ label: 'IAM for the project: grant the roles to the Ductape service account here', url: 'https://console.cloud.google.com/iam-admin/iam?project=<PROJECT_ID>' }],
217
+ }
218
+ : { step: 3, who: 'you', title: 'Grant roles for the services you want Ductape to manage', notes: ['For example roles/storage.admin for buckets, roles/cloudsql.admin for Cloud SQL, roles/pubsub.admin for Pub/Sub, roles/spanner.admin for Spanner.'] },
219
+ {
220
+ step: 4, who: 'you', title: 'Create a key file outside any repository',
221
+ commands: ['mkdir -p ~/.ductape-keys && chmod 700 ~/.ductape-keys', 'gcloud iam service-accounts keys create ~/.ductape-keys/<PROJECT_ID>.json --iam-account ductape@<PROJECT_ID>.iam.gserviceaccount.com', 'chmod 600 ~/.ductape-keys/<PROJECT_ID>.json'],
222
+ notes: ['The key file is a long-lived secret. Keep it out of the project directory and out of chat.'],
223
+ },
224
+ {
225
+ step: 5, who: 'ductape', title: 'Create the connection',
226
+ commands: [`ductape cloud connections create --provider gcp --name "<NAME>" --tag <TAG>${deploy ? ' --deploy' : ''}`],
227
+ notes: [...(deploy ? ['--deploy adds the "deploy" scope, which makes validation check the permissions above.'] : []), 'Tags are lowercase letters, digits and underscores (for example gcp_main). Use the same tag in the steps below.'],
228
+ },
229
+ {
230
+ step: 6, who: 'ductape', title: 'Complete it with the key file',
231
+ commands: [`ductape cloud connections complete <TAG> --service-account-file ~/.ductape-keys/<PROJECT_ID>.json${deploy ? ' [--runtime-service-account <EMAIL>]' : ''}`],
232
+ notes: deploy ? ['--runtime-service-account is the account your services run as. Without it, deploys use the project\'s default compute account.'] : undefined,
233
+ },
234
+ { step: 7, who: 'ductape', title: 'Validate it', commands: ['ductape cloud connections validate <TAG>'], notes: ['A failure names exactly which permissions or APIs are missing.', ...(deploy ? ['Building source runs as Cloud Build\'s own service account, which is separate from this one. If a build fails with a permission error, the account named in the build log also needs roles/artifactregistry.writer, roles/logging.logWriter and roles/storage.objectViewer.'] : [])] },
235
+ { step: 8, who: 'you', title: 'Remove the local key file', notes: ['Ductape keeps its own encrypted copy in your workspace secrets, so the local file is no longer needed.'], commands: ['rm ~/.ductape-keys/<PROJECT_ID>.json'] },
236
+ ],
237
+ ...(deploy ? {
238
+ access: { roles, apis },
239
+ creates: GCP_DEPLOY_CREATES,
240
+ troubleshooting: GCP_DEPLOY_TROUBLESHOOTING,
241
+ next: [
242
+ `Build and deploy: ductape deploy builds create --file build.json --dir <SOURCE_DIR> --wait (the file names the connection tag and a region such as europe-west2).`,
243
+ 'See what is deployed: ductape deploy deployments list, or the Deployments section of the product in the workbench.',
244
+ GCP_DEPLOY_SAFETY,
245
+ ],
246
+ } : {}),
247
+ };
248
+ }
249
+ if (provider === 'aws') {
250
+ return {
251
+ ...base, supported: true,
252
+ summary: 'Lets Ductape manage resources in your AWS account by assuming an IAM role that you create and that trusts Ductape.',
253
+ steps: [
254
+ { step: 1, who: 'ductape', title: 'Create the connection', commands: ['ductape cloud connections create --provider aws --name "<NAME>" --tag <TAG>'], notes: ['The response contains an external_id and a trust_policy. Keep them for the next step.'] },
255
+ { step: 2, who: 'you', title: 'Create an IAM role with that trust policy', notes: ['In IAM, create a role whose trust policy is the one returned in step 1, then attach permissions for the services you want Ductape to manage (for example S3, SQS, RDS).'] },
256
+ { step: 3, who: 'ductape', title: 'Complete it with the role', commands: ['ductape cloud connections complete <TAG> --role-arn arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>'] },
257
+ { step: 4, who: 'ductape', title: 'Validate it', commands: ['ductape cloud connections validate <TAG>'] },
258
+ ],
259
+ };
260
+ }
261
+ if (provider === 'azure') {
262
+ return {
263
+ ...base, supported: true,
264
+ summary: 'Lets Ductape manage resources in your Azure subscription using a service principal you register.',
265
+ steps: [
266
+ { step: 1, who: 'ductape', title: 'Create the connection', commands: ['ductape cloud connections create --provider azure --name "<NAME>" --tag <TAG>'] },
267
+ { step: 2, who: 'you', title: 'Register an app and assign roles', notes: ['Register an Azure AD app (service principal), create a client secret, and assign RBAC roles for storage, Service Bus, PostgreSQL, Cosmos DB and AI Search on the subscription.'] },
268
+ { step: 3, who: 'you', title: 'Put the client secret in an environment variable', commands: ['read -s AZURE_CLIENT_SECRET && export AZURE_CLIENT_SECRET'], notes: ['This keeps the secret out of the command line and shell history.'] },
269
+ { step: 4, who: 'ductape', title: 'Complete it', commands: ['ductape cloud connections complete <TAG> --tenant-id <TENANT_ID> --subscription-id <SUBSCRIPTION_ID> --client-id <CLIENT_ID> --client-secret-env AZURE_CLIENT_SECRET --default-location <REGION>'] },
270
+ { step: 5, who: 'ductape', title: 'Validate it', commands: ['ductape cloud connections validate <TAG>'] },
271
+ ],
272
+ };
273
+ }
274
+ if (provider === 'mongodb_atlas') {
275
+ return {
276
+ ...base, supported: true,
277
+ summary: 'Lets Ductape manage MongoDB Atlas clusters and database users through an Atlas API key.',
278
+ steps: [
279
+ { step: 1, who: 'ductape', title: 'Create the connection', commands: ['ductape cloud connections create --provider mongodb_atlas --name "<NAME>" --tag <TAG>'] },
280
+ { step: 2, who: 'you', title: 'Create an Atlas API key', notes: ['In Atlas: Security, Project Identity and Access, Applications, API Keys. Give it Project Owner under Project permissions. Note the Project ID from Project Settings.'] },
281
+ { step: 3, who: 'you', title: 'Put the private key in an environment variable', commands: ['read -s ATLAS_PRIVATE_KEY && export ATLAS_PRIVATE_KEY'] },
282
+ { step: 4, who: 'ductape', title: 'Complete it', commands: ['ductape cloud connections complete <TAG> --project-id <ATLAS_PROJECT_ID> --atlas-public-key <PUBLIC_KEY> --atlas-private-key-env ATLAS_PRIVATE_KEY'] },
283
+ { step: 5, who: 'ductape', title: 'Validate it', commands: ['ductape cloud connections validate <TAG>'] },
284
+ ],
285
+ };
286
+ }
287
+ return {
288
+ ...base, supported: true,
289
+ summary: 'Lets Ductape manage Neo4j Aura instances through Aura API credentials.',
290
+ steps: [
291
+ { step: 1, who: 'ductape', title: 'Create the connection', commands: ['ductape cloud connections create --provider neo4j_aura --name "<NAME>" --tag <TAG>'] },
292
+ { step: 2, who: 'you', title: 'Create Aura API credentials', notes: ['In the Aura console, create API credentials and note the client ID and client secret.'] },
293
+ { step: 3, who: 'you', title: 'Put the client secret in an environment variable', commands: ['read -s AURA_CLIENT_SECRET && export AURA_CLIENT_SECRET'] },
294
+ { step: 4, who: 'ductape', title: 'Complete it', commands: ['ductape cloud connections complete <TAG> --aura-client-id <CLIENT_ID> --aura-client-secret-env AURA_CLIENT_SECRET [--aura-instance-id <INSTANCE_ID>]'] },
295
+ { step: 5, who: 'ductape', title: 'Validate it', commands: ['ductape cloud connections validate <TAG>'] },
296
+ ],
297
+ };
298
+ }
299
+ // ---- Previewing ------------------------------------------------------------------------------------------------------
300
+ const HIDDEN = '[hidden]';
301
+ /** A copy of a request body that is safe to print: secrets and key material are replaced, everything else is kept. */
302
+ export function maskConnectionBody(body) {
303
+ const masked = { ...body };
304
+ for (const field of ['client_secret', 'atlas_private_key', 'aura_client_secret', 'connection_string']) {
305
+ if (masked[field] !== undefined)
306
+ masked[field] = HIDDEN;
307
+ }
308
+ const key = masked.service_account_json;
309
+ if (key && typeof key === 'object') {
310
+ const { type, project_id, client_email, client_id } = key;
311
+ masked.service_account_json = { type, project_id, client_email, client_id, private_key: HIDDEN };
312
+ }
313
+ else if (typeof key === 'string') {
314
+ masked.service_account_json = HIDDEN;
315
+ }
316
+ return masked;
317
+ }
@@ -10,7 +10,8 @@ export declare function deleteProduct(ctx: WorkspaceContext, productId: string):
10
10
  export declare function summarizeConnectedApp(value: unknown): unknown;
11
11
  export declare function listProductApps(ctx: WorkspaceContext, productIdOrTag: string, full?: boolean): Promise<unknown[]>;
12
12
  export declare function listProductAppActions(ctx: WorkspaceContext, product: string, appTag: string): Promise<unknown[]>;
13
- export declare function getProductAppAction(ctx: WorkspaceContext, product: string, appTag: string, actionTag: string): Promise<unknown>;
13
+ export declare function markUnboundCatalogueAction(action: unknown): Record<string, unknown>;
14
+ export declare function getProductAppAction(ctx: WorkspaceContext, product: string, appTag: string, actionTag: string, env?: string): Promise<unknown>;
14
15
  export declare function connectMarketplaceApp(ctx: WorkspaceContext, product: string, appTag: string, envs: Array<{
15
16
  app_env_slug: string;
16
17
  product_env_slug: string;
@@ -39,6 +40,48 @@ export interface MarketplaceSearchOptions {
39
40
  export declare function listMarketplaceCategories(ctx: WorkspaceContext): Promise<unknown[]>;
40
41
  export declare function getMarketplaceApp(ctx: WorkspaceContext, tag: string, full?: boolean): Promise<unknown>;
41
42
  export declare function searchMarketplaceApps(ctx: WorkspaceContext, opts: MarketplaceSearchOptions): Promise<unknown[]>;
43
+ export declare function rankMarketplaceApps(apps: unknown[], opts: MarketplaceSearchOptions): {
44
+ items: {
45
+ match: {
46
+ score: number;
47
+ matched_terms: string[];
48
+ query_terms: string[];
49
+ };
50
+ }[];
51
+ total_matches_in_snapshot: number;
52
+ returned_count: number;
53
+ truncated: boolean;
54
+ next_cursor: null;
55
+ coverage: {
56
+ scope: string;
57
+ source: string;
58
+ upstream_completeness: string;
59
+ pagination_supported: boolean;
60
+ scanned_count: number;
61
+ limitation: string;
62
+ };
63
+ };
64
+ export declare function discoverMarketplaceApps(ctx: WorkspaceContext, opts: MarketplaceSearchOptions): Promise<{
65
+ items: {
66
+ match: {
67
+ score: number;
68
+ matched_terms: string[];
69
+ query_terms: string[];
70
+ };
71
+ }[];
72
+ total_matches_in_snapshot: number;
73
+ returned_count: number;
74
+ truncated: boolean;
75
+ next_cursor: null;
76
+ coverage: {
77
+ scope: string;
78
+ source: string;
79
+ upstream_completeness: string;
80
+ pagination_supported: boolean;
81
+ scanned_count: number;
82
+ limitation: string;
83
+ };
84
+ }>;
42
85
  export interface TierQuery {
43
86
  provider?: string;
44
87
  resource_type?: string;
@@ -216,12 +216,37 @@ export async function listProductAppActions(ctx, product, appTag) {
216
216
  return actionsFromLinkedApp(app).map(actionSummary);
217
217
  }
218
218
  }
219
- export async function getProductAppAction(ctx, product, appTag, actionTag) {
219
+ export function markUnboundCatalogueAction(action) {
220
+ if (!action || typeof action !== 'object' || Array.isArray(action))
221
+ throw new Error('Catalogue action response is malformed');
222
+ return {
223
+ ...action,
224
+ contract_scope: 'catalogue_unbound',
225
+ runtime_authoritative: false,
226
+ warnings: ['No environment was selected. This catalogue action may differ from the connected runtime version. Repeat products apps actions get with --env before generating runtime payloads or executing.'],
227
+ };
228
+ }
229
+ export async function getProductAppAction(ctx, product, appTag, actionTag, env) {
230
+ if (env) {
231
+ const productTag = /^[a-f\d]{24}$/i.test(product)
232
+ ? String((await getProduct(ctx, { id: product })).tag ?? '')
233
+ : product;
234
+ if (!productTag)
235
+ throw new Error('Product tag could not be resolved for action contract lookup');
236
+ const result = await client(ctx).getPath('/integrations/v1/action-contract', {
237
+ ...workspaceAuthQuery(ctx), product_tag: productTag, env_slug: env, access_tag: appTag, action_tag: actionTag,
238
+ });
239
+ const resolution = result.resolution;
240
+ if (!result.action || !resolution?.version || !resolution?.access_tag || result.executed_action !== false) {
241
+ throw new Error('Environment-bound action contract is unavailable; refusing to substitute the latest app version');
242
+ }
243
+ return result;
244
+ }
220
245
  await requireLinkedApp(ctx, product, appTag);
221
246
  try {
222
247
  const result = unwrapOne(await proxy(ctx).execute('app', 'actions.fetch', [appTag, actionTag]));
223
248
  if (result)
224
- return result;
249
+ return markUnboundCatalogueAction(result);
225
250
  }
226
251
  catch {
227
252
  // Compatibility fallback for deployed SDKs predating app.actions.
@@ -232,7 +257,7 @@ export async function getProductAppAction(ctx, product, appTag, actionTag) {
232
257
  const action = actionsFromLinkedApp(app).find((item) => item && typeof item === 'object' && item.tag === actionTag);
233
258
  if (!action)
234
259
  throw new Error(`Action "${actionTag}" was not found on linked app "${appTag}"`);
235
- return action;
260
+ return markUnboundCatalogueAction(action);
236
261
  }
237
262
  export async function connectMarketplaceApp(ctx, product, appTag, envs) {
238
263
  if (envs.length === 0)
@@ -446,13 +471,17 @@ export async function updateAppAction(ctx, appTag, actionTag, body) {
446
471
  export async function deleteAppAction(ctx, appTag, actionTag) {
447
472
  return proxy(ctx).execute('actions', 'delete', [appTag, actionTag]);
448
473
  }
474
+ function marketplaceVersion(app) {
475
+ const versions = Array.isArray(app.versions) ? app.versions : [];
476
+ return app.currentVersion && typeof app.currentVersion === 'object'
477
+ ? app.currentVersion
478
+ : versions.find(version => version.latest === true) ?? versions[0] ?? {};
479
+ }
449
480
  function searchableMarketplaceText(app) {
450
481
  if (!app || typeof app !== 'object')
451
482
  return '';
452
483
  const value = app;
453
- const version = value.currentVersion && typeof value.currentVersion === 'object'
454
- ? value.currentVersion
455
- : {};
484
+ const version = marketplaceVersion(value);
456
485
  const actions = Array.isArray(version.actions) ? version.actions : [];
457
486
  const webhooks = Array.isArray(version.webhooks) ? version.webhooks : [];
458
487
  return [
@@ -479,10 +508,7 @@ function summarizeMarketplaceApp(value) {
479
508
  if (!value || typeof value !== 'object')
480
509
  return value;
481
510
  const app = value;
482
- const versions = Array.isArray(app.versions) ? app.versions : [];
483
- const current = app.currentVersion && typeof app.currentVersion === 'object'
484
- ? app.currentVersion
485
- : versions.find((version) => version.latest === true) ?? versions[0] ?? {};
511
+ const current = marketplaceVersion(app);
486
512
  const actions = Array.isArray(current.actions) ? current.actions : [];
487
513
  return {
488
514
  tag: app.tag,
@@ -506,22 +532,49 @@ export async function getMarketplaceApp(ctx, tag, full = false) {
506
532
  return full ? app : summarizeMarketplaceApp(app);
507
533
  }
508
534
  export async function searchMarketplaceApps(ctx, opts) {
509
- const result = await client(ctx).getPath('/apps/v1/domains/all');
510
- const apps = unwrapList(result);
511
- const terms = (opts.query ?? '').toLowerCase().split(/\s+/).filter(Boolean);
535
+ return (await discoverMarketplaceApps(ctx, opts)).items;
536
+ }
537
+ export function rankMarketplaceApps(apps, opts) {
538
+ const terms = [...new Set((opts.query ?? '').toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean))];
512
539
  const category = opts.category?.toLowerCase();
513
- const filtered = apps.filter((app) => {
514
- const text = searchableMarketplaceText(app);
515
- if (terms.length > 0 && !terms.every((term) => text.includes(term)))
516
- return false;
517
- if (!category)
518
- return true;
540
+ const ranked = apps.flatMap((app, index) => {
519
541
  if (!app || typeof app !== 'object')
520
- return false;
521
- const domains = app.domains;
522
- return Array.isArray(domains) && domains.some((domain) => typeof domain === 'string' && domain.toLowerCase().includes(category));
523
- });
524
- return filtered.slice(0, Math.max(1, Math.min(opts.limit ?? 20, 100))).map(summarizeMarketplaceApp);
542
+ return [];
543
+ const value = app;
544
+ const domains = value.domains;
545
+ if (category && !(Array.isArray(domains) && domains.some(domain => typeof domain === 'string' && domain.toLowerCase().includes(category))))
546
+ return [];
547
+ const text = searchableMarketplaceText(app);
548
+ const identity = [value.app_name, value.name, value.tag].filter(item => typeof item === 'string').join(' ').toLowerCase();
549
+ const matched = terms.filter(term => text.includes(term));
550
+ if (terms.length && !matched.length)
551
+ return [];
552
+ const score = matched.length * 10 + matched.filter(term => identity.includes(term)).length * 5;
553
+ return [{ app, index, score, matched }];
554
+ }).sort((a, b) => b.score - a.score || a.index - b.index);
555
+ const limit = Number.isFinite(opts.limit) ? Math.max(1, Math.min(Math.floor(opts.limit), 100)) : 20;
556
+ return {
557
+ items: ranked.slice(0, limit).map(({ app, score, matched }) => ({
558
+ ...summarizeMarketplaceApp(app),
559
+ match: { score, matched_terms: matched, query_terms: terms },
560
+ })),
561
+ total_matches_in_snapshot: ranked.length,
562
+ returned_count: Math.min(ranked.length, limit),
563
+ truncated: ranked.length > limit,
564
+ next_cursor: null,
565
+ coverage: {
566
+ scope: 'public_marketplace',
567
+ source: '/apps/v1/domains/all',
568
+ upstream_completeness: 'unknown',
569
+ pagination_supported: false,
570
+ scanned_count: apps.length,
571
+ limitation: 'Ranked lexical matches within the returned public catalogue snapshot only; private workspace capabilities are not searched. Refine the query or increase limit (maximum 100) when truncated. The upstream route exposes no pagination or completeness guarantee.',
572
+ },
573
+ };
574
+ }
575
+ export async function discoverMarketplaceApps(ctx, opts) {
576
+ const result = await client(ctx).getPath('/apps/v1/domains/all');
577
+ return rankMarketplaceApps(unwrapList(result), opts);
525
578
  }
526
579
  export async function listCloudTiers(ctx, q) {
527
580
  const params = workspaceAuthQuery(ctx);
@@ -1,4 +1,4 @@
1
- export type SDKModule = 'product' | 'app' | 'databases' | 'graph' | 'webhooks' | 'notifications' | 'messageBrokers' | 'storage' | 'vector' | 'caches' | 'sessions' | 'quotas' | 'actions' | 'feature' | 'jobs' | 'logs' | 'resilience' | 'health' | 'fallback' | 'secrets' | 'models' | 'cloud';
1
+ export type SDKModule = 'product' | 'app' | 'databases' | 'graph' | 'webhooks' | 'notifications' | 'messageBrokers' | 'storage' | 'vector' | 'caches' | 'sessions' | 'quotas' | 'rateLimits' | 'actions' | 'feature' | 'jobs' | 'logs' | 'resilience' | 'health' | 'fallback' | 'secrets' | 'models' | 'cloud';
2
2
  export interface SdkProxyContext {
3
3
  apiUrl: string;
4
4
  workspaceId: string;
@@ -12,6 +12,12 @@ export type CrudVerb = 'create' | 'list' | 'get' | 'update' | 'delete' | 'connec
12
12
  export declare const CONNECT_IDENTIFIER_FIELD: Partial<Record<SDKModule, string>>;
13
13
  export declare function resolveResourceType(name: string): SDKModule;
14
14
  export declare function proxyMethodForVerb(verb: CrudVerb): string;
15
+ /**
16
+ * Rate limit policies live under `ductape.rateLimit.policies`, so the proxy method is
17
+ * `policies.<verb>`. Policies are immutable per tag: `update` only changes name and description,
18
+ * and new limits are published under a new tag.
19
+ */
20
+ export declare function proxyMethodForModule(module: SDKModule, method: string): string;
15
21
  /** Build params array matching Workbench sdkProxy.ts conventions */
16
22
  export declare function buildCrudParams(module: SDKModule, method: string, productTag: string, args: {
17
23
  tag?: string;
@@ -29,6 +29,11 @@ export const RESOURCE_MODULES = {
29
29
  secrets: 'secrets',
30
30
  quota: 'quotas',
31
31
  quotas: 'quotas',
32
+ ratelimit: 'rateLimits',
33
+ ratelimits: 'rateLimits',
34
+ 'rate-limit': 'rateLimits',
35
+ 'rate-limits': 'rateLimits',
36
+ rate_limits: 'rateLimits',
32
37
  health: 'health',
33
38
  healthcheck: 'health',
34
39
  healthchecks: 'health',
@@ -65,6 +70,14 @@ export function proxyMethodForVerb(verb) {
65
70
  return 'list';
66
71
  return verb;
67
72
  }
73
+ /**
74
+ * Rate limit policies live under `ductape.rateLimit.policies`, so the proxy method is
75
+ * `policies.<verb>`. Policies are immutable per tag: `update` only changes name and description,
76
+ * and new limits are published under a new tag.
77
+ */
78
+ export function proxyMethodForModule(module, method) {
79
+ return module === 'rateLimits' ? `policies.${method}` : method;
80
+ }
68
81
  /** Build params array matching Workbench sdkProxy.ts conventions */
69
82
  export function buildCrudParams(module, method, productTag, args) {
70
83
  const { tag, body } = args;
@@ -191,6 +204,7 @@ export function listResourceTypes() {
191
204
  'sessions',
192
205
  'secrets',
193
206
  'quotas',
207
+ 'rate-limits',
194
208
  'health',
195
209
  'fallback',
196
210
  'models',
@@ -208,6 +222,7 @@ const PRODUCT_COMPONENT_KEYS = {
208
222
  messageBrokers: ['message_brokers', 'messageBrokers', 'brokers'],
209
223
  sessions: ['sessions'],
210
224
  quotas: ['quota', 'quotas'],
225
+ rateLimits: ['rateLimits'],
211
226
  health: ['healthchecks'],
212
227
  fallback: ['fallback', 'fallbacks'],
213
228
  models: ['models'],
@@ -221,5 +236,9 @@ export function listComponentsFromProduct(module, value) {
221
236
  ? envelope.data
222
237
  : envelope;
223
238
  const key = keys.find((candidate) => Array.isArray(product[candidate]));
224
- return key ? product[key] : [];
239
+ const items = key ? product[key] : [];
240
+ // Deleted rate limit tags stay on the product (they are reserved) but are not live policies.
241
+ return module === 'rateLimits'
242
+ ? items.filter((item) => item?.deleted !== true)
243
+ : items;
225
244
  }
@@ -0,0 +1,30 @@
1
+ export declare const MAX_SOURCE_BYTES: number;
2
+ /** Left out of every upload. `.env` files are the usual place for secrets, and they must not travel with the source. */
3
+ export declare const DEFAULT_EXCLUDES: string[];
4
+ export interface IPackedSource {
5
+ file: string;
6
+ sha256: string;
7
+ bytes: number;
8
+ /** The patterns that were left out, so what was not uploaded is never a surprise. */
9
+ excluded: string[];
10
+ /** `.dockerignore` lines that could not be honoured. */
11
+ warnings: string[];
12
+ cleanup(): void;
13
+ }
14
+ /** Reads `.dockerignore` into tar exclude patterns. Negations ("!keep") cannot be expressed and are reported, not guessed at. */
15
+ export declare function readDockerignore(dir: string): {
16
+ patterns: string[];
17
+ warnings: string[];
18
+ };
19
+ /** Packs a directory into a compressed archive, hashes it, and refuses anything over the size limit. */
20
+ export declare function packSource(dir: string, options?: {
21
+ dockerfile?: string;
22
+ exclude?: string[];
23
+ }): Promise<IPackedSource>;
24
+ export interface IUploadTicket {
25
+ url: string;
26
+ method: string;
27
+ headers: Record<string, string>;
28
+ }
29
+ /** Sends the archive straight to the bucket in the customer's cloud account. Ductape's servers never see it. */
30
+ export declare function uploadSource(ticket: IUploadTicket, file: string): Promise<void>;