@ductape/cli 0.4.9 → 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.
@@ -1,4 +1,4 @@
1
- export type DeployRemoteOperation = 'releases.register' | 'plans.create' | 'plans.approve' | 'plans.apply' | 'deployments.list' | 'deployments.get' | 'deployments.journal' | 'functions.list' | 'versions.list' | 'versions.history' | 'versions.deprecate' | 'versions.undeprecate' | 'versions.retire';
1
+ export type DeployRemoteOperation = 'releases.register' | 'plans.create' | 'plans.approve' | 'plans.apply' | 'deployments.list' | 'deployments.get' | 'deployments.journal' | 'environments.list' | 'environments.policy' | 'functions.list' | 'versions.list' | 'versions.history' | 'versions.deprecate' | 'versions.undeprecate' | 'versions.retire';
2
2
  export interface IDeployRemoteArgs {
3
3
  file?: string;
4
4
  id?: string;
@@ -6,9 +6,13 @@ export interface IDeployRemoteArgs {
6
6
  function?: string;
7
7
  version?: string;
8
8
  env?: string;
9
+ /** "function" or "service": narrows a listing. */
10
+ kind?: string;
9
11
  reason?: string;
10
12
  sunset?: string;
11
13
  replacement?: string;
14
+ requireApproval?: string;
15
+ allowAgentApply?: string;
12
16
  }
13
17
  /** Calls made on behalf of an agent say so, so the control plane never lets them approve or retire. */
14
18
  export declare function actorHeaders(): Record<string, string>;
@@ -28,6 +28,11 @@ function readJsonFile(file, what) {
28
28
  throw new Error(`The ${what} at ${resolved} is not valid: ${error instanceof Error ? error.message : String(error)}`);
29
29
  }
30
30
  }
31
+ function checkedKind(kind) {
32
+ if (kind !== undefined && kind !== 'function' && kind !== 'service')
33
+ throw new Error('--kind must be "function" or "service"');
34
+ return kind;
35
+ }
31
36
  const need = (value, name) => {
32
37
  if (!value)
33
38
  throw new Error(`${name} is required`);
@@ -45,9 +50,15 @@ export async function runDeployRemote(operation, args) {
45
50
  extra.env = args.env;
46
51
  if (args.version)
47
52
  extra.version = args.version;
53
+ if (checkedKind(args.kind))
54
+ extra.kind = args.kind;
55
+ }
56
+ if (operation === 'functions.list') {
57
+ if (args.product)
58
+ extra.productTag = args.product;
59
+ if (checkedKind(args.kind))
60
+ extra.kind = args.kind;
48
61
  }
49
- if (operation === 'functions.list' && args.product)
50
- extra.productTag = args.product;
51
62
  const query = new URLSearchParams(workspaceAuthQuery(ctx, extra)).toString();
52
63
  const call = (method, route, body) => api.request(method, `${BASE}${route}?${query}`, body, actorHeaders());
53
64
  const fn = (suffix = '') => `/functions/${need(args.product, '--product')}/${need(args.function, '--function')}/versions${suffix}`;
@@ -75,6 +86,21 @@ export async function runDeployRemote(operation, args) {
75
86
  case 'deployments.journal':
76
87
  result = await call('GET', `/deployments/${need(args.id, 'the deployment id')}/journal`);
77
88
  break;
89
+ case 'environments.list':
90
+ result = await call('GET', `/products/${need(args.product, '--product')}/environments`);
91
+ break;
92
+ case 'environments.policy': {
93
+ const flag = (value, name) => {
94
+ if (value !== 'true' && value !== 'false')
95
+ throw new Error(`${name} is required and must be true or false`);
96
+ return value === 'true';
97
+ };
98
+ result = await call('PUT', `/products/${need(args.product, '--product')}/environments/${need(args.env, '--env')}/policy`, {
99
+ requireHumanApproval: flag(args.requireApproval, '--require-approval'),
100
+ allowAgentApply: flag(args.allowAgentApply, '--allow-agent-apply'),
101
+ });
102
+ break;
103
+ }
78
104
  case 'functions.list':
79
105
  result = await call('GET', '/functions');
80
106
  break;
package/dist/index.js CHANGED
@@ -110,17 +110,19 @@ remote('releases', 'register', 'Register an immutable release from a JSON file',
110
110
  remote('plans', 'create', 'Create a plan from a JSON file; nothing is changed', (c) => c.requiredOption('--file <file>', 'Plan request JSON')).action(op('plans.create'));
111
111
  remote('plans', 'approve <planId>', 'Approve a plan (a person only; refused for agents)').action(op('plans.approve'));
112
112
  remote('plans', 'apply <planId>', 'Apply an approved or permitted plan').action(op('plans.apply'));
113
- remote('deployments', 'list', 'List deployments', (c) => c.option('--product <tag>').option('--env <env>').option('--fn-version <version>')).action(op('deployments.list'));
113
+ remote('deployments', 'list', 'List deployments (functions and services)', (c) => c.option('--product <tag>').option('--env <env>').option('--fn-version <version>').option('--kind <kind>', 'function or service')).action(op('deployments.list'));
114
114
  remote('deployments', 'get <deploymentId>', 'Show one deployment').action(op('deployments.get'));
115
115
  remote('deployments', 'journal <deploymentId>', 'Show a deployment\'s journal').action(op('deployments.journal'));
116
- remote('functions', 'list', 'List functions with their latest available version', (c) => c.option('--product <tag>')).action(op('functions.list'));
116
+ remote('environments', 'list', 'List a product\'s environments with how each is governed and what is deployed in it', (c) => c.requiredOption('--product <tag>')).action(op('environments.list'));
117
+ remote('environments', 'policy', 'Set whether applying to an environment needs a person\'s approval (a person only)', (c) => c.requiredOption('--product <tag>').requiredOption('--env <slug>').requiredOption('--require-approval <bool>', 'true: a person must approve each plan').requiredOption('--allow-agent-apply <bool>', 'true: an agent may apply without approval (ignored when approval is required)')).action(op('environments.policy'));
118
+ remote('functions', 'list', 'List functions and services with their latest available version', (c) => c.option('--product <tag>').option('--kind <kind>', 'function or service')).action(op('functions.list'));
117
119
  const versionTarget = (c) => c.requiredOption('--product <tag>').requiredOption('--function <name>');
118
120
  remote('versions', 'list', 'List the versions of a function', versionTarget).action(op('versions.list'));
119
121
  remote('versions', 'history', 'Show what happened to a version', (c) => versionTarget(c).requiredOption('--fn-version <version>')).action(op('versions.history'));
120
122
  remote('versions', 'deprecate', 'Deprecate a version (existing deployments keep serving)', (c) => versionTarget(c).requiredOption('--fn-version <version>').requiredOption('--reason <text>').option('--sunset <iso-date>').option('--replacement <version>')).action(op('versions.deprecate'));
121
123
  remote('versions', 'undeprecate', 'Make a deprecated version available again', (c) => versionTarget(c).requiredOption('--fn-version <version>')).action(op('versions.undeprecate'));
122
124
  remote('versions', 'retire', 'Retire a deprecated version that is no longer serving (a person only; final)', (c) => versionTarget(c).requiredOption('--fn-version <version>')).action(op('versions.retire'));
123
- remote('builds', 'create', 'Build source in your own cloud account and register a release from the image', (c) => c.requiredOption('--file <file>', 'Build JSON: productTag, functionName, version, connectionTag, region, contract, config, verification')
125
+ remote('builds', 'create', 'Build source in your own cloud account and register a release from the image', (c) => c.requiredOption('--file <file>', 'Build JSON. A function: productTag, functionName, version, connectionTag, region, contract, config, verification. A service: kind "service", productTag, serviceName, version, connectionTag, region, port, checks, config')
124
126
  .option('--dir <dir>', 'Source directory (default: the current directory)')
125
127
  .option('--builder <builder>', 'dockerfile (default) or buildpacks')
126
128
  .option('--dockerfile <path>', 'Dockerfile inside the source (default: Dockerfile)')
@@ -41,6 +41,11 @@ export interface IGuideStep {
41
41
  title: string;
42
42
  commands?: string[];
43
43
  notes?: string[];
44
+ /** Console pages that do the step without a terminal. */
45
+ links?: Array<{
46
+ label: string;
47
+ url: string;
48
+ }>;
44
49
  }
45
50
  export interface IConnectionGuide {
46
51
  provider: CloudProviderName;
@@ -57,11 +62,27 @@ export interface IConnectionGuide {
57
62
  }>;
58
63
  apis: string[];
59
64
  };
65
+ /** What a deploy connection will make in the customer's project, so nothing is a surprise. */
66
+ creates?: string[];
67
+ /** Errors people meet during setup, and what fixes each. */
68
+ troubleshooting?: Array<{
69
+ problem: string;
70
+ fix: string;
71
+ }>;
72
+ /** What to do once the connection is active. */
73
+ next?: string[];
60
74
  }
61
75
  export declare const GCP_DEPLOY_ROLE_LIST: {
62
76
  role: string;
63
77
  for: string;
64
78
  }[];
79
+ /** Everything a deploy through a GCP connection leaves in the customer's project. All of it is labelled as Ductape's. */
80
+ export declare const GCP_DEPLOY_CREATES: string[];
81
+ export declare 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.";
82
+ export declare const GCP_DEPLOY_TROUBLESHOOTING: {
83
+ problem: string;
84
+ fix: string;
85
+ }[];
65
86
  export declare const GCP_DEPLOY_APIS: string[];
66
87
  export declare function connectionGuide(providerInput: string, purposeInput?: string): IConnectionGuide;
67
88
  /** A copy of a request body that is safe to print: secrets and key material are replaced, everything else is kept. */
@@ -153,6 +153,24 @@ export const GCP_DEPLOY_ROLE_LIST = [
153
153
  { role: 'roles/iam.serviceAccountUser', for: 'deploy a service that runs as the runtime service account' },
154
154
  { role: 'roles/browser', for: 'read the project to find its number' },
155
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
+ ];
156
174
  export const GCP_DEPLOY_APIS = [
157
175
  'run.googleapis.com', 'cloudbuild.googleapis.com', 'artifactregistry.googleapis.com', 'secretmanager.googleapis.com',
158
176
  'storage.googleapis.com', 'cloudresourcemanager.googleapis.com', 'iam.googleapis.com',
@@ -183,10 +201,20 @@ export function connectionGuide(providerInput, purposeInput = 'resources') {
183
201
  ? 'Lets Ductape deploy to Cloud Run and build source in your own GCP project, using a service account you create and control.'
184
202
  : 'Lets Ductape manage storage, databases, brokers, graphs and vectors in your GCP project, using a service account you create and control.',
185
203
  steps: [
186
- { step: 1, who: 'you', title: 'Enable the APIs', commands: [`gcloud services enable ${apis.join(' ')} --project <PROJECT_ID>`] },
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
+ },
187
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"'] },
188
212
  deploy
189
- ? { step: 3, who: 'you', title: 'Grant the roles Ductape Deploy uses', commands: roles.map((r) => bind(r.role)), notes: roles.map((r) => `${r.role}: ${r.for}`) }
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
+ }
190
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.'] },
191
219
  {
192
220
  step: 4, who: 'you', title: 'Create a key file outside any repository',
@@ -206,7 +234,16 @@ export function connectionGuide(providerInput, purposeInput = 'resources') {
206
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.'] : [])] },
207
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'] },
208
236
  ],
209
- ...(deploy ? { access: { roles, apis } } : {}),
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
+ } : {}),
210
247
  };
211
248
  }
212
249
  if (provider === 'aws') {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ductape/cli",
3
- "version": "0.4.9",
3
+ "version": "0.5.0",
4
4
  "description": "Ductape CLI — local platform, login, link projects, and manage resources via the proxy (Workbench-compatible)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",