@huaweidevtools/aishell-dsh-deploy 0.0.14 → 0.0.16

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 (54) hide show
  1. package/README.md +25 -9
  2. package/cordis.patch.yml +12 -3
  3. package/lib/data/permission-registry.json +1 -1
  4. package/lib/index.js +5271 -1402
  5. package/lib/types/auth-http.d.ts +36 -4
  6. package/lib/types/auth-obs-signer.d.ts +8 -5
  7. package/lib/types/auth-signer.d.ts +6 -1
  8. package/lib/types/bridge.d.ts +4 -4
  9. package/lib/types/bss.d.ts +159 -0
  10. package/lib/types/catalog.d.ts +118 -0
  11. package/lib/types/credentials.d.ts +64 -18
  12. package/lib/types/d2-render.d.ts +74 -0
  13. package/lib/types/data-paths.d.ts +10 -0
  14. package/lib/types/deployment-state.d.ts +90 -13
  15. package/lib/types/existing.d.ts +79 -0
  16. package/lib/types/gates/cost_gate.d.ts +38 -16
  17. package/lib/types/gates/credential_gate.d.ts +29 -3
  18. package/lib/types/gates/design_gate.d.ts +72 -0
  19. package/lib/types/gates/mirror.d.ts +1 -1
  20. package/lib/types/gates/plan_gate.d.ts +116 -0
  21. package/lib/types/gates/provider_installed.d.ts +32 -0
  22. package/lib/types/gates/terraform_env.d.ts +15 -2
  23. package/lib/types/hcl.d.ts +176 -0
  24. package/lib/types/index.d.ts +18 -4
  25. package/lib/types/network-checks.d.ts +67 -0
  26. package/lib/types/permission/gate.d.ts +6 -6
  27. package/lib/types/permission/registry.d.ts +11 -0
  28. package/lib/types/plan.d.ts +68 -0
  29. package/lib/types/prompt.d.ts +5 -4
  30. package/lib/types/rating-map.d.ts +132 -0
  31. package/lib/types/security-groups.d.ts +16 -23
  32. package/lib/types/terraform-run.d.ts +32 -0
  33. package/lib/types/tools/annotations.d.ts +1 -1
  34. package/lib/types/tools/balance_summary.d.ts +1 -1
  35. package/lib/types/tools/deployment.d.ts +3 -3
  36. package/lib/types/tools/design.d.ts +54 -0
  37. package/lib/types/tools/errors.d.ts +22 -4
  38. package/lib/types/tools/examples.d.ts +1 -1
  39. package/lib/types/tools/existing_resources.d.ts +1 -1
  40. package/lib/types/tools/index.d.ts +26 -12
  41. package/lib/types/tools/openapi.d.ts +19 -9
  42. package/lib/types/tools/pricing.d.ts +213 -0
  43. package/lib/types/tools/provider_schema.d.ts +1 -1
  44. package/lib/types/tools/specs.d.ts +41 -0
  45. package/lib/types/tools/terraform.d.ts +27 -25
  46. package/lib/types/topology.d.ts +232 -0
  47. package/lib/types/types.d.ts +1 -1
  48. package/lib/types/utils/hash.d.ts +15 -5
  49. package/package.json +4 -2
  50. package/lib/types/gates/networking_gate.d.ts +0 -9
  51. package/lib/types/schemas/cost.d.ts +0 -108
  52. package/lib/types/schemas/networking.d.ts +0 -115
  53. package/lib/types/tools/cost.d.ts +0 -16
  54. package/lib/types/tools/networking.d.ts +0 -13
@@ -11,10 +11,11 @@
11
11
  * via `loadCredentials`.
12
12
  * - Explicit `creds` arg: a caller that already holds the pair.
13
13
  *
14
- * IAM *verification* no longer runs through here — it moved to the shared
15
- * `credentials-store/verify` module when `auth` moved to `aishell-credentials`.
16
- * This client stays the funnel for the cloud calls the tools make, which is
17
- * what the read-only gate below needs to cover.
14
+ * IAM *verification* does not run through here: it lives in the shared
15
+ * `credentials-store/verify` module, owned by `aishell-credentials` alongside
16
+ * the form that collects the pair. This client is the funnel for the cloud
17
+ * calls THIS plugin's tools make, which is what the read-only gate below has to
18
+ * cover.
18
19
  *
19
20
  * Verified end-to-end against HuaweiCloud APIs:
20
21
  * - IAM GET /v3/projects → 200
@@ -22,10 +23,24 @@
22
23
  * - BSS GET /v2/promotions/benefits/coupons → 200
23
24
  */
24
25
  import { type Credentials } from "./credentials.js";
26
+ /**
27
+ * Whether a URL may be signed for.
28
+ *
29
+ * The scheme is checked as strictly as the host. An `http://` URL would put the
30
+ * access key on the wire in cleartext, and HMAC signing offers no protection
31
+ * when the signature itself travels unprotected alongside the key id it was
32
+ * derived from.
33
+ *
34
+ * @param url - the request URL.
35
+ * @returns a message naming the refusal, or `undefined` to proceed.
36
+ */
37
+ export declare function denyUnsignedTarget(url: URL): string | undefined;
25
38
  export interface SignedHttpResponse {
26
39
  status: number;
27
40
  headers: Record<string, string>;
28
41
  body: string;
42
+ /** True when the body was cut at {@link MAX_RESPONSE_BYTES}. */
43
+ truncated?: boolean;
29
44
  }
30
45
  /**
31
46
  * Send a signed HTTP request to a HuaweiCloud API endpoint.
@@ -41,4 +56,21 @@ export interface SignedHttpResponse {
41
56
  * read. The gate is unconditional — see permission/gate.ts.
42
57
  */
43
58
  export declare function signedHttp(method: string, url: URL, body: string, extraHeaders?: Record<string, string>, creds?: Credentials): Promise<SignedHttpResponse>;
59
+ /**
60
+ * Read a response body, stopping at {@link MAX_RESPONSE_BYTES}.
61
+ *
62
+ * Streamed rather than `response.text()`, so the cap stops the read instead of
63
+ * being applied to a string that has already cost the memory it was meant to
64
+ * save. Exported because it IS the policy and should be testable on its own —
65
+ * a test that re-implemented this loop would verify a copy.
66
+ *
67
+ * @param response - the response to drain.
68
+ * @returns the body kept, and whether it was cut.
69
+ */
70
+ export declare function readCapped(response: {
71
+ body: ReadableStream<Uint8Array> | null;
72
+ }): Promise<{
73
+ readonly body: string;
74
+ readonly truncated: boolean;
75
+ }>;
44
76
  //# sourceMappingURL=auth-http.d.ts.map
@@ -8,12 +8,15 @@
8
8
  * CanonicalizedHeaders, CanonicalizedResource — joined by "\n"
9
9
  * - Date header: RFC 1123 GMT (not X-Sdk-Date)
10
10
  *
11
- * Ported from esdk-obs-nodejs 3.26.8 `doAuth` (utils.js line 1497-1578). The
12
- * SDK is CommonJS + log4js + callback-style + signature-negotiation; importing
13
- * it would pollute the ESM architecture, so the algorithm is ported instead.
14
- * The signing logic is HuaweiCloud's public spec — no copyright concern.
11
+ * Ported from esdk-obs-nodejs 3.26.8 `doAuth`. The SDK is CommonJS + log4js +
12
+ * callback-style + signature-negotiation; importing it would pollute the ESM
13
+ * architecture, so the algorithm is ported instead. The signing logic is
14
+ * HuaweiCloud's public spec — no copyright concern.
15
15
  *
16
- * Verified against the SDK source at /home/eushing/Downloads/utils.js.
16
+ * The port was checked against that SDK's source: the six StringToSign
17
+ * segments, the `x-obs-meta-` trim rule and the sub-resource whitelist are
18
+ * taken from it verbatim rather than reconstructed from the documentation,
19
+ * which states the shape without the exceptions.
17
20
  */
18
21
  export interface ObsSigningParams {
19
22
  method: string;
@@ -12,6 +12,12 @@
12
12
  * than AWS sigv4 — no date/region-derived key chain); the signature
13
13
  * is HMAC-SHA256(sk, string-to-sign), hex-encoded.
14
14
  *
15
+ * There is no region here, and that is not an omission. AWS sigv4 derives the
16
+ * signing key from a region and therefore binds a signature to one; this
17
+ * scheme does not, so the same request signs identically for every region
18
+ * (verified). The region appears in the URL's host, which IS signed, so
19
+ * naming the wrong one fails on the host rather than on the region.
20
+ *
15
21
  * Status: verified end-to-end against real HuaweiCloud APIs:
16
22
  * - IAM GET /v3/projects → 200
17
23
  * - BSS GET /v2/accounts/customer-accounts/balances → 200
@@ -26,7 +32,6 @@ export interface SigningParams {
26
32
  body: string;
27
33
  ak: string;
28
34
  sk: string;
29
- region: string;
30
35
  /** STS token if using temporary credentials. */
31
36
  securityToken?: string | undefined;
32
37
  }
@@ -8,16 +8,16 @@
8
8
  * that registrar's role — collecting the declarations — and converts each one
9
9
  * into a DSH `ToolDefinition`.
10
10
  *
11
- * ## Why the handlers are not rewritten
11
+ * ## Why the handler contract is kept as it is
12
12
  *
13
13
  * Their result shape is a good internal contract: success and failure are
14
14
  * explicit, and every diagnostic is somewhere the model reads. Flattening 5000
15
15
  * lines of handlers into canonical values would be a mechanical diff across
16
16
  * every file, and a mechanical diff is where a misplaced return hides until a
17
- * tool runs. So the handlers stay, and this module is the only place that knows
18
- * both vocabularies.
17
+ * tool runs. So the handlers speak their own vocabulary, and this module is the
18
+ * only place that knows both.
19
19
  *
20
- * ## What DSH needs that the handlers did not produce
20
+ * ## What this module adds to reach DSH
21
21
  *
22
22
  * - **A canonical output value.** DSH tools return a lossless-JSON value and
23
23
  * render it. That value is the result itself, so `structuredContent`
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Asking the BSS rating API what something costs.
3
+ *
4
+ * ## What the API will not tell you, and what it will
5
+ *
6
+ * An on-demand inquiry takes `usage_measure_id` — the unit the quantity is
7
+ * expressed in. It is required, and nothing publishes its value: the API
8
+ * contract describes it as "the unit, e.g. hours", and `usage-types` returns
9
+ * only `code: "Duration"`. So a caller cannot look it up, and guessing is what
10
+ * a naive implementation does.
11
+ *
12
+ * The API answers a wrong value with the right one:
13
+ *
14
+ * ```
15
+ * POST usage_measure_id: 999
16
+ * 400 "Convert from value measure(9) to measure unit(4) error"
17
+ * ```
18
+ *
19
+ * Verified for compute, RDS and DCS. That turns an unknown into a fact the
20
+ * call itself reports, so this module submits once, reads the correction, and
21
+ * retries — then remembers it for the rest of the process. No table of magic
22
+ * numbers, and no unit that goes stale when a service changes its billing.
23
+ *
24
+ * ## Why the classification comes from the catalogue
25
+ *
26
+ * `cloud_service_type` and `resource_type` are BSS's own codes, and the
27
+ * mapping from a terraform resource type is not mechanical: `ecs` bills under
28
+ * `ec2`, `nat_gateway` under `natgateway`, an RDS instance under
29
+ * `hws.resource.type.rds.vm` rather than `…rds`. A table of 1961 provider types
30
+ * would be wrong within a month. The catalogue is the data those codes live in,
31
+ * so it is asked instead.
32
+ *
33
+ * @module @huaweidevtools/aishell-dsh-deploy/bss
34
+ */
35
+ /** One product to price. */
36
+ export interface RateProduct {
37
+ /** The caller's identifier, echoed back so a batch can be matched up. */
38
+ readonly id: string;
39
+ readonly cloudServiceType: string;
40
+ readonly resourceType: string;
41
+ readonly resourceSpec: string;
42
+ readonly region: string;
43
+ readonly availabilityZone?: string;
44
+ /** The capacity, for a product sold by size. */
45
+ readonly resourceSize?: number;
46
+ readonly sizeMeasureId?: number;
47
+ readonly usageFactor: string;
48
+ /** How many units to price. A month of hours is 730. */
49
+ readonly usageValue: number;
50
+ }
51
+ /** What the rating API answered. */
52
+ export interface RateAnswer {
53
+ readonly ok: boolean;
54
+ /** The response body, parsed when `ok`. */
55
+ readonly body?: unknown;
56
+ /** The failure as the API stated it, when not `ok`. */
57
+ readonly failure?: RateFailure;
58
+ }
59
+ /**
60
+ * Why an inquiry did not produce a price.
61
+ *
62
+ * `notOffered` is separated from the rest because it is the only failure that
63
+ * changing the request cannot fix: the account does not carry the product, or
64
+ * the region does not sell it.
65
+ */
66
+ export type RateFailure = {
67
+ readonly kind: 'not-offered';
68
+ readonly detail: string;
69
+ } | {
70
+ readonly kind: 'malformed';
71
+ readonly detail: string;
72
+ } | {
73
+ readonly kind: 'unknown';
74
+ readonly detail: string;
75
+ };
76
+ /**
77
+ * Price a batch of products in one inquiry.
78
+ *
79
+ * One call, many products: the API prices each entry independently and echoes
80
+ * the caller's `id`, so a batch is atomic — one project, one currency, one
81
+ * moment. A product whose classification turns out to need a different usage
82
+ * unit is retried once on its own, because the batch has already been refused.
83
+ *
84
+ * @param projectId - the region's project id.
85
+ * @param products - the products to price.
86
+ * @returns one answer per product, in input order.
87
+ */
88
+ export declare function rateProducts(projectId: string, products: readonly RateProduct[]): Promise<Map<string, RateAnswer>>;
89
+ /**
90
+ * The unit the API said it wanted, when it said so.
91
+ *
92
+ * The body nests the useful part: `…[msg]:{"error_code":"CBC.6050","error_msg":
93
+ * "Convert from value measure(9) to measure unit(4) error"}` — a JSON object
94
+ * inside a string inside JSON. The number after "measure unit" is the one to
95
+ * resubmit.
96
+ *
97
+ * @param failure - the failure the API reported.
98
+ * @returns the corrective unit, or `undefined` when this was not that error.
99
+ */
100
+ export declare function readMeasureCorrection(failure: RateFailure | undefined): number | undefined;
101
+ /**
102
+ * The price of one product out of a successful batch.
103
+ *
104
+ * `amount` is what this account pays; `official_website_amount` is the list
105
+ * price. The account's own is the figure to quote — the list price would
106
+ * overstate the bill by the account's discount.
107
+ *
108
+ * @param body - the parsed response.
109
+ * @param productId - the caller's id for that product.
110
+ * @returns the amounts, or `undefined` when the response carries none for it.
111
+ */
112
+ export declare function readPrice(body: unknown, productId: string): {
113
+ readonly amount: number;
114
+ readonly listAmount: number;
115
+ readonly currency: string;
116
+ } | undefined;
117
+ /** The measure unit this process has learned for a factor, for a diagnostic. */
118
+ export declare function learnedMeasureUnit(usageFactor: string): number | undefined;
119
+ /** Forget every learned unit. For a test that must not inherit one. */
120
+ export declare function resetLearnedMeasureUnits(): void;
121
+ /**
122
+ * The spec codes one resource type is sold under, from the catalogue.
123
+ *
124
+ * ## Why this exists
125
+ *
126
+ * The rating API takes a `resource_spec`, and nothing publishes that
127
+ * vocabulary: a caller that guesses answers `CBC.99006006 Product not found`,
128
+ * which reads as "this product does not exist" about a product that is sold.
129
+ * The guess is the problem, so the catalogue is asked instead.
130
+ *
131
+ * `POST /v2/products/resource-specs-query` takes the service, the resource
132
+ * type, the region and a charge mode, and lists every spec sold that way. Both
133
+ * axes matter: the list is per REGION — the same service offers different specs
134
+ * in different regions — and per CHARGE MODE, so a product sold only on
135
+ * subscription returns an empty on-demand list.
136
+ *
137
+ * ## What an empty list does and does not mean
138
+ *
139
+ * Empty means "nothing under this resource type is sold that way here". It does
140
+ * NOT mean the resource type is unpriceable in general, and a NON-empty list
141
+ * does not promise the rating call will accept an entry: a service can list
142
+ * specs whose billing item does not exist. The rating call remains the authority
143
+ * on whether a price comes back; this answers only what the catalogue offers.
144
+ *
145
+ * @param credentials - the pair to sign with.
146
+ * @param query - the service, resource type, region and charge mode to ask about.
147
+ * @returns the spec codes, in catalogue order; empty when none are sold.
148
+ */
149
+ export declare function listResourceSpecs(credentials: {
150
+ readonly ak: string;
151
+ readonly sk: string;
152
+ }, query: {
153
+ readonly serviceType: string;
154
+ readonly resourceType: string;
155
+ readonly region: string;
156
+ /** `1` subscription, `3` on-demand. */
157
+ readonly chargeMode?: '1' | '3';
158
+ }): Promise<readonly string[]>;
159
+ //# sourceMappingURL=bss.d.ts.map
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Reading the catalogue responses: what a region actually sells.
3
+ *
4
+ * ## Why this exists
5
+ *
6
+ * A `.tf` file names a flavour and an image by ID: `flavor_id = "c7.large.2"`,
7
+ * `image_id = "img-xxx"`. `terraform validate` checks only that those are
8
+ * strings — a clearly invented `flavor_id` passes. The value is checked at
9
+ * apply time by the cloud, after the user has approved a plan and a price.
10
+ *
11
+ * So a design can be schema-valid, priced, approved, and fail on the first
12
+ * resource. This module reads the two catalogues that close that gap: the
13
+ * flavours and images a region offers, and the database specs with the zones
14
+ * that carry them.
15
+ *
16
+ * ## Why the calls are described here and not in the prompt
17
+ *
18
+ * Every URL, query parameter and response field below was established against
19
+ * the live API. A model reconstructing them from a one-line instruction in the
20
+ * prompt gets them wrong — `vcpus` arrives as a string while `ram` arrives as a
21
+ * number, RDS lists its zones in `az_status` whose values are `normal` or
22
+ * `unsupported`, and an engine name is a path segment rather than a query. Those
23
+ * are exactly the details that read plausible and fail.
24
+ *
25
+ * Pricing lives in `bss.ts` and `rating-map.ts`; this module only answers what
26
+ * can be bought.
27
+ *
28
+ * @module @huaweidevtools/aishell-dsh-deploy/catalog
29
+ */
30
+ /**
31
+ * The region's project id, from IAM.
32
+ *
33
+ * Every region-scoped API needs it in the path, and it is not the account id:
34
+ * one account has a project per region. `loadAccount()` already resolves the
35
+ * account; this is the region part of the same identity.
36
+ */
37
+ export interface ProjectRef {
38
+ readonly id: string;
39
+ readonly region: string;
40
+ }
41
+ /** One compute flavour the region offers in a given availability zone. */
42
+ export interface Flavor {
43
+ readonly id: string;
44
+ readonly name: string;
45
+ readonly vcpus: number;
46
+ /** Memory in MiB, as the API reports it. */
47
+ readonly ramMb: number;
48
+ /** Local disk in GiB, `0` for a flavour with none. */
49
+ readonly diskGb: number;
50
+ }
51
+ /** One image that can boot an instance in the region. */
52
+ export interface Image {
53
+ readonly id: string;
54
+ readonly name: string;
55
+ /** e.g. `Ubuntu 22.04 server 64bit`. */
56
+ readonly os: string;
57
+ readonly minDiskGb: number;
58
+ readonly minRamMb: number;
59
+ }
60
+ /**
61
+ * The flavours an ECS response lists.
62
+ *
63
+ * `ram` is MiB and arrives as a number; `vcpus` and `disk` arrive as strings
64
+ * (`"48"`, `"0"`). The whole list is returned rather than a subset because the
65
+ * caller decides what to show — and a filter here would hide the very flavour
66
+ * a `.tf` names and turn "not offered" into "not found".
67
+ *
68
+ * @param body - the parsed `cloudservers/flavors` response.
69
+ * @returns the flavours, in the order the API gave them.
70
+ */
71
+ export declare function readFlavors(body: unknown): Flavor[];
72
+ /**
73
+ * The images an IMS response lists.
74
+ *
75
+ * `min_disk` and `min_ram` are what the image needs from the flavour it boots
76
+ * on, which is the constraint a reader has to check against the chosen flavour
77
+ * — so they are kept rather than dropped.
78
+ *
79
+ * @param body - the parsed `cloudimages` response.
80
+ * @returns the images.
81
+ */
82
+ export declare function readImages(body: unknown): Image[];
83
+ /** One database instance specification the region offers. */
84
+ export interface DatabaseFlavor {
85
+ readonly id: string;
86
+ readonly specCode: string;
87
+ readonly vcpus: number;
88
+ readonly ramGb: number;
89
+ /** The modes it can be bought in: `single`, `ha`, `replica`, … */
90
+ readonly instanceMode: string;
91
+ /** Zones where this spec can be deployed, keyed by zone id. */
92
+ readonly zones: Readonly<Record<string, string>>;
93
+ }
94
+ /**
95
+ * The database specs an RDS `flavors/<engine>` response lists.
96
+ *
97
+ * `az_status` is the field that makes the list usable for a design: a spec
98
+ * exists region-wide but not in every zone, so a design that names a spec has
99
+ * to be checked against the zone it placed the instance in. Reporting a spec as
100
+ * available without its zones would approve a combination the cloud refuses.
101
+ *
102
+ * @param body - the parsed `flavors/<engine>` response.
103
+ * @returns the specs, in the order the API gave them.
104
+ */
105
+ export declare function readDatabaseFlavors(body: unknown): DatabaseFlavor[];
106
+ /**
107
+ * Whether a spec is deployable in one zone.
108
+ *
109
+ * The API reports `normal` for an available zone and `unsupported` for one it
110
+ * does not serve. Anything else — an unexpected status — counts as unavailable,
111
+ * because the safe reading of "I do not understand this" is "do not approve it".
112
+ *
113
+ * @param flavor - the spec.
114
+ * @param zone - the zone to ask about.
115
+ * @returns whether the spec can be deployed there.
116
+ */
117
+ export declare function deployableInZone(flavor: DatabaseFlavor, zone: string): boolean;
118
+ //# sourceMappingURL=catalog.d.ts.map
@@ -7,14 +7,15 @@
7
7
  * no adapter and no mirror here: a rotation in the form applies to the very
8
8
  * next tool call, and a clear means what it says.
9
9
  *
10
- * Two things the shared store deliberately does not know, and this module
11
- * supplies:
10
+ * One thing the shared store deliberately does not know, and this module
11
+ * supplies: **the account identity**. The store holds secrets and nothing
12
+ * else, so `{account_id, name}` is resolved from IAM on demand and cached for
13
+ * this process.
12
14
  *
13
- * 1. **The region.** Not a credential: a deployment choice the plugin config
14
- * owns, applied to every signed call and to the terraform subprocess env.
15
- * 2. **The account identity.** The store holds secrets and nothing else, so
16
- * `{account_id, name}` is resolved from IAM on demand and cached for this
17
- * process.
15
+ * The region is not one of them. It does not enter the signature — verified:
16
+ * two regions produce byte-identical Authorization headers — so it is not a
17
+ * property of the account. It belongs to each RESOURCE in a plan, and
18
+ * {@link configuredRegion} exposes only the fallback an operator may have set.
18
19
  *
19
20
  * @module @huaweidevtools/aishell-dsh-deploy/credentials
20
21
  */
@@ -22,13 +23,18 @@ import type { CredentialsStore } from '@huaweidevtools/aishell-dsh-credentials-s
22
23
  /**
23
24
  * One credential set, as the signing paths here take it.
24
25
  *
25
- * `region` rides alongside because every HuaweiCloud caller in this plugin
26
- * needs one and none may guess: the plugin config decides it, not the store.
26
+ * AK, SK and the optional STS token — and nothing else. `region` is
27
+ * deliberately NOT here: it does not enter the signature (verified — two
28
+ * regions produce byte-identical Authorization headers), so it is not a
29
+ * property of the account. It is a property of each RESOURCE, read from the
30
+ * plan, and every caller that needs one says where it came from.
31
+ *
32
+ * Keeping it out is what lets one deployment span several regions: a
33
+ * deployment-wide region would have to be right for every resource at once.
27
34
  */
28
35
  export interface Credentials {
29
36
  readonly ak: string;
30
37
  readonly sk: string;
31
- readonly region: string;
32
38
  /** Present only for STS (temporary) credentials. */
33
39
  readonly securityToken?: string;
34
40
  }
@@ -42,12 +48,30 @@ export interface AccountIdentity {
42
48
  readonly account_id: string;
43
49
  readonly account_name: string;
44
50
  }
45
- /** How this module reaches the host: the plugin's store and its region. */
51
+ /**
52
+ * How this module reaches the host: the plugin's credential store.
53
+ *
54
+ * ## Why `region` is optional, and why there is no default
55
+ *
56
+ * A region is not an account property — it does not enter the signature — so
57
+ * it cannot come from the store. It comes from each resource's plan.
58
+ *
59
+ * This field is the fallback for a plan that names none, and it exists only
60
+ * because terraform has one of its own (`HW_REGION_NAME`). The two must be the
61
+ * same value: if terraform were told one region while pricing assumed another,
62
+ * the quote would describe a price list column the deployment never bills
63
+ * against. So the value is set by an operator in the plugin config, or not at
64
+ * all — a built-in default would be that guess, with nothing on screen to
65
+ * contradict it.
66
+ *
67
+ * When it is absent, a resource whose plan names no region is reported as
68
+ * unpriced rather than priced against a guess.
69
+ */
46
70
  export interface CredentialSource {
47
71
  /** The plugin's credential store; read per call, never captured. */
48
72
  readonly store: CredentialsStore;
49
- /** Region every signed request and terraform env carries. */
50
- readonly region: string;
73
+ /** The fallback region an operator configured, if any. */
74
+ readonly region?: string | undefined;
51
75
  }
52
76
  /**
53
77
  * Bind the credential source. Called once from the plugin's `apply()`.
@@ -58,16 +82,32 @@ export interface CredentialSource {
58
82
  * once — and the alternative (threading a reader through 18 tool registrars)
59
83
  * would touch every file for a case that does not exist.
60
84
  *
61
- * @param next - the store and region this plugin was configured with.
85
+ * @param next - the store, and the region an operator configured if any.
62
86
  */
63
87
  export declare function configureCredentials(next: CredentialSource): void;
64
88
  /**
65
89
  * Read the current credentials.
66
90
  *
67
- * @returns the pair with the configured region, or `undefined` when the AK/SK
68
- * pair is incomplete.
91
+ * @returns the AK/SK pair, or `undefined` when it is incomplete.
69
92
  */
70
93
  export declare function readStoredCredentials(): Credentials | undefined;
94
+ /**
95
+ * The region an operator configured, when one was.
96
+ *
97
+ * Not a credential and not guessed: see {@link CredentialSource.region} for
98
+ * what reads it. A caller that needs a region for one resource takes it from
99
+ * the plan; this is only the fallback for a plan that names none, and for the
100
+ * `HW_REGION_NAME` terraform runs under.
101
+ *
102
+ * Unlike the credential read, an unbound source is not an error here. This
103
+ * answers "was a region configured", and the honest answer for a process that
104
+ * configured none is `undefined` — the same answer as an operator who left it
105
+ * unset. Raising the wiring error instead would turn a supported configuration
106
+ * (no default region) into a startup fault.
107
+ *
108
+ * @returns the configured region, or `undefined`.
109
+ */
110
+ export declare function configuredRegion(): string | undefined;
71
111
  /**
72
112
  * Load credentials or fail with the remedy the model can act on.
73
113
  *
@@ -88,10 +128,16 @@ export declare function hasCredentials(): boolean;
88
128
  * account" is answered by the same call the credential form uses — no second
89
129
  * notion of validity.
90
130
  *
131
+ * It is routed through `'global'`, which is IAM's own spelling for the
132
+ * non-regional endpoint: the question is about the credential, not about any
133
+ * one region, and a regional replica would add a region to a call that does
134
+ * not have one to give.
135
+ *
91
136
  * ## Why the failure is thrown rather than folded into `undefined`
92
137
  *
93
- * `undefined` used to cover both reasons verification can fail, and the two
94
- * call for opposite responses. A credential IAM *rejected* is the person's to
138
+ * The two reasons verification can fail call for opposite responses, and
139
+ * folding them into one `undefined` would send the reader to the wrong one. A
140
+ * credential IAM *rejected* is the person's to
95
141
  * fix: re-authenticate. A credential IAM never saw — a timeout, DNS, a proxy —
96
142
  * is nobody's mistake, and telling the person to re-authenticate sends them to
97
143
  * re-enter a credential that was already correct.
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Drawing the topology: D2 source, then an SVG.
3
+ *
4
+ * ## Why D2 and not hand-built SVG
5
+ *
6
+ * A network topology is a nested graph with edges, and every hand-rolled
7
+ * layout for one has to solve two things badly: where a box goes, and where
8
+ * its edges land. D2 solves both, and it is the format's own vocabulary —
9
+ * containers nest, arrows connect, `near:` pins an annotation panel.
10
+ *
11
+ * The cost is real and worth stating: the WASM build is ~21 MB packaged, and
12
+ * the compile step instantiates it once per process (~1.1 s cold, then ~70 ms
13
+ * per diagram). It runs inside a worker thread that D2 owns, so the
14
+ * instantiation does not block this process's event loop; {@link closeD2}
15
+ * terminates that worker, which is the only way to hand the ~600 MB of WASM
16
+ * linear memory back.
17
+ *
18
+ * ## What D2 does and does not carry
19
+ *
20
+ * It carries the PICTURE. It does not carry data: custom `vars` are discarded,
21
+ * an attribute written as a child (`cidr: "10.0.0.0/16"`) becomes a visible
22
+ * second box, and a mistyped attribute or an edge to an undefined node are
23
+ * accepted silently. So nothing here is read back out of D2 — the topology is
24
+ * derived from HCL and D2 is only where it is drawn. That direction matters:
25
+ * a generator is exact, a parser of pictures is not.
26
+ *
27
+ * ## Theme
28
+ *
29
+ * `render` is given both `themeID` and `darkThemeID`; D2 emits both palettes
30
+ * into one SVG and selects between them with `@media
31
+ * (prefers-color-scheme: dark)`. The result follows the viewer's setting with
32
+ * no JavaScript.
33
+ *
34
+ * @module @huaweidevtools/aishell-dsh-deploy/d2-render
35
+ */
36
+ import type { Topology, TopologyEdge } from './topology.ts';
37
+ /** One render in, one render out; the caller owns timing and disposal. */
38
+ export interface RenderResult {
39
+ /** The D2 source that was rendered, so a reader can see what was drawn. */
40
+ readonly source: string;
41
+ /** The SVG, with no XML declaration so it embeds directly in HTML. */
42
+ readonly svg: string;
43
+ }
44
+ /**
45
+ * Draw the topology.
46
+ *
47
+ * @param topology - the derived picture.
48
+ * @param edges - the relationships to draw, from `<from-address>` to
49
+ * `<to-address>`. Only addresses the topology knows are drawn.
50
+ * @returns the D2 source and the SVG it renders to.
51
+ * @throws when the generated D2 source does not compile. That is a defect in
52
+ * this module rather than in the user's configuration — the generator is
53
+ * what produced the text — so the message names the generated fragment.
54
+ */
55
+ export declare function renderTopology(topology: Topology, edges: readonly TopologyEdge[]): Promise<RenderResult>;
56
+ /**
57
+ * Generate the D2 source for one topology.
58
+ *
59
+ * The shape of the output is fixed by what D2 accepts, and every choice here
60
+ * comes from something D2 refused:
61
+ *
62
+ * - Nothing is written as an attribute child. `cidr: "10.0.0.0/16"` inside a
63
+ * node's block renders as its own box, which would put a stray rectangle
64
+ * in every subnet. Facts go into the node's LABEL instead.
65
+ * - Facts are separated by `·` rather than aligned into columns, because D2
66
+ * treats a leading `|` as a block-string terminator.
67
+ * - No `vars` block: D2 discards everything under it except `d2-config`.
68
+ *
69
+ * @param topology - the derived picture.
70
+ * @param edges - the relationships to draw.
71
+ * @returns D2 source text.
72
+ */
73
+ export declare function toD2(topology: Topology, edges: readonly TopologyEdge[]): string;
74
+ //# sourceMappingURL=d2-render.d.ts.map
@@ -67,4 +67,14 @@ export declare function terraformRoot(): string;
67
67
  export declare function terraformBinDir(): string;
68
68
  /** The terraform provider-plugin cache: `<DSH_HOME>/terraform/plugins`. */
69
69
  export declare function terraformPluginDir(): string;
70
+ /**
71
+ * Where a user-supplied terraform binary path is recorded.
72
+ *
73
+ * `terraform_install` accepts a `terraform_path` the user picked, and every
74
+ * later call has to find that same binary. Passing it per-call was not an
75
+ * option — the path belongs to the deployment, not to one tool invocation — so
76
+ * it is written here and read by `resolveTerraformEnv`, which makes a
77
+ * subsequent `terraform_plan` use the binary `terraform_install` reported.
78
+ */
79
+ export declare function terraformPathRecord(): string;
70
80
  //# sourceMappingURL=data-paths.d.ts.map