@huaweidevtools/aishell-dsh-deploy 0.0.15 → 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
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Running the terraform binary: the one place a subprocess is spawned.
3
+ *
4
+ * ## Why this is its own module
5
+ *
6
+ * `terraform_plan`, `terraform_validate`, `terraform_show` and the tools that
7
+ * only READ what terraform produced all need to run it. Hosting the runner
8
+ * beside the tool registrations would make every such module import the tool
9
+ * module — a dependency from a reader to a registrar, which is backwards and
10
+ * makes the import graph look cyclic even when it is not.
11
+ *
12
+ * ## The read-only funnel
13
+ *
14
+ * Every invocation passes through {@link denyTerraformMutation}. The tool-level
15
+ * gate names `terraform_apply` explicitly, which covers today's call sites;
16
+ * deciding here means a future call site cannot introduce a mutation that the
17
+ * read-only switch silently fails to see.
18
+ *
19
+ * @module @huaweidevtools/aishell-dsh-deploy/terraform-run
20
+ */
21
+ /** Shared terraform runner: resolve env, then spawn. */
22
+ export interface TerraformResult {
23
+ exitCode: number;
24
+ stdout: string;
25
+ stderr: string;
26
+ /** True if stdout was truncated at MAX_OUTPUT_BYTES (output incomplete). */
27
+ stdoutTruncated?: boolean;
28
+ /** True if stderr was truncated at MAX_OUTPUT_BYTES. */
29
+ stderrTruncated?: boolean;
30
+ }
31
+ export declare function runTerraform(cwd: string, args: string[], extraEnv?: string[]): Promise<TerraformResult>;
32
+ //# sourceMappingURL=terraform-run.d.ts.map
@@ -55,7 +55,7 @@ export declare const READ_ONLY_LOCAL: ToolAnnotations;
55
55
  /**
56
56
  * Writes files inside the deployment workspace only; creates nothing, destroys
57
57
  * nothing, no external system. Re-running with the same input converges.
58
- * e.g. create_deployment, update_networking, update_cost.
58
+ * e.g. create_deployment, validate_design, price_resources.
59
59
  */
60
60
  export declare const LOCAL_WRITE: ToolAnnotations;
61
61
  /**
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * BSS account-balance + coupon queries for the balance_summary field
3
- * returned by list_existing_resources (§3.2 + cost review §7 step 9).
3
+ * returned by list_existing_resources, at the reuse-and-budget decision point.
4
4
  *
5
5
  * Why these are aggregated into list_existing_resources instead of a
6
6
  * separate tool: the deployment flow calls list_existing_resources at the
@@ -1,14 +1,14 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
2
  /**
3
- * create_deployment + delete_deployment (§3.2).
3
+ * create_deployment + delete_deployment.
4
4
  *
5
5
  * create: create or reuse a deployment workspace directory, writing
6
6
  * .deployment.json (state snapshot). If the dir exists and is a deployment,
7
7
  * return existing info + status. If it exists but is non-empty and not a
8
8
  * deployment, refuse.
9
9
  *
10
- * delete: refuse if the deployment still has live cloud resources (check
11
- * terraform.tfstate); if clean, remove the directory.
10
+ * delete: refuse if the deployment still has live cloud resources (checks
11
+ * the configured terraform backend); if clean, remove the directory.
12
12
  */
13
13
  export declare function registerDeploymentTools(registrar: ToolRegistrar): void;
14
14
  //# sourceMappingURL=deployment.d.ts.map
@@ -0,0 +1,54 @@
1
+ /**
2
+ * `validate_design` — check the network design and draw it.
3
+ *
4
+ * ## Where this sits in the flow
5
+ *
6
+ * The design stage of a deployment is the network: VPCs, subnets, address
7
+ * ranges, security groups. None of it needs a flavour, an image, or a resource
8
+ * id — the things that only make sense once the network exists. So the design
9
+ * stage needs no cloud credentials, and this tool needs none either.
10
+ *
11
+ * That is what makes the ordering work. A model can write the network `.tf`
12
+ * alone, have it checked and drawn, show the picture, and only then begin to
13
+ * fill in compute resources. The alternative — deriving the picture from a
14
+ * `plan` — would require the whole configuration first, including the specs
15
+ * and ids that the network design is what determines.
16
+ *
17
+ * ## What it checks, and what it deliberately does not
18
+ *
19
+ * `terraform validate` is run when the provider is installed, because it is
20
+ * the authoritative check on the configuration: provider attribute names,
21
+ * required arguments, value formats, and reference resolution. Nothing here
22
+ * duplicates it.
23
+ *
24
+ * What it CANNOT check is everything that spans blocks — overlapping subnets,
25
+ * a subnet outside its VPC, a gateway outside its subnet, a rule open to the
26
+ * world. `terraform validate` reports `Success!` for all four. Those come from
27
+ * `network-checks` instead.
28
+ *
29
+ * When the provider is NOT installed, `terraform validate` cannot run, and the
30
+ * tool says so rather than implying the configuration is checked. The diagram
31
+ * is still drawn: it derives from the `.tf` text, which does not need a
32
+ * provider, and a picture with an explicit "not validated" note is more useful
33
+ * than no picture.
34
+ *
35
+ * ## The diagram
36
+ *
37
+ * Written beside the configuration as `topology.svg` and `topology.d2`, and
38
+ * reported by absolute path. An absolute path is what the shell's Markdown
39
+ * image resolution needs: a relative one resolves against the session's
40
+ * workspace, and the deployment directory need not be inside it. The file is
41
+ * served to the browser through the authenticated `/api/file` route, which
42
+ * sends `Content-Security-Policy: sandbox; default-src 'none'` — so an SVG
43
+ * written here cannot act as a document even if its text were attacker-chosen.
44
+ *
45
+ * @module @huaweidevtools/aishell-dsh-deploy/tools/design
46
+ */
47
+ import type { ToolRegistrar } from '../types.ts';
48
+ /**
49
+ * Register `validate_design`.
50
+ *
51
+ * @param registrar - the capture surface this plugin's tools register into.
52
+ */
53
+ export declare function registerDesignTool(registrar: ToolRegistrar): void;
54
+ //# sourceMappingURL=design.d.ts.map
@@ -9,12 +9,30 @@ export type ToolCtx = ToolContext;
9
9
  /** What a tool handler may return. */
10
10
  export type ToolResult = CallToolResult;
11
11
  /**
12
- * A successful tool result: text content (and optional structured content).
12
+ * A successful tool result carrying a JSON value.
13
13
  *
14
- * Tools return `content` arrays. `isError` is omitted
15
- * (defaults to false) on success.
14
+ * ## Where the text goes
15
+ *
16
+ * Only `structuredContent` is set here. The model reads what `bridge.ts`
17
+ * renders, and that renderer serializes this value — so writing the same JSON
18
+ * into `content[0].text` as well would put one copy in the result that nothing
19
+ * ever reads, and pay for it twice: once in the handler, once in the harness's
20
+ * snapshot of the returned value.
21
+ *
22
+ * `content` is therefore empty on this path. It stays a required field because
23
+ * `fail()` fills it — a diagnostic has no structure to carry and is read
24
+ * straight from the text — and because the type is the harness's shape, not
25
+ * this module's.
26
+ *
27
+ * The parameter is `object` rather than `Record<string, unknown>` so a typed
28
+ * result — a contract interface, a summary — passes without a cast to an index
29
+ * signature it does not have. Every such value is JSON-serializable, which is
30
+ * the only property this needs.
31
+ *
32
+ * @param value - the tool's output, already structured.
33
+ * @returns the result that carries it.
16
34
  */
17
- export declare function ok(text: string, structured?: Record<string, unknown>): CallToolResult;
35
+ export declare function okJson(value: object): CallToolResult;
18
36
  /**
19
37
  * A failed tool result: `isError: true` + text content.
20
38
  *
@@ -1,4 +1,4 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
- /** terraform_examples_export (§3.2). */
2
+ /** terraform_examples_export: the provider's own `.tf` corpus, on disk. */
3
3
  export declare function registerExamplesTool(registrar: ToolRegistrar): void;
4
4
  //# sourceMappingURL=examples.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
2
  /**
3
- * list_existing_resources (§3.2).
3
+ * list_existing_resources.
4
4
  *
5
5
  * Lists HuaweiCloud resources the user already owns, for reuse in a deployment.
6
6
  * Two-stage query against RMS (Resource Management Service) — the unified
@@ -3,18 +3,29 @@ import { z } from "zod";
3
3
  /**
4
4
  * Register this plugin's tools on the DSH tool registry.
5
5
  *
6
- * Tool count: 17.
6
+ * Tool count: 18.
7
7
  *
8
- * 部署目录 2 + 状态文件 2 + 华为云能力 4 + terraform 9 = 17
8
+ * 部署目录 2 + 设计校验 1 + 规格 1 + 报价 1 + 华为云能力 4 + terraform 9 = 18
9
9
  *
10
- * `auth` is not among them: it lives in `aishell-credentials`, which owns the
11
- * credential lifecycle and the form that collects AK/SK. A verify tool here
12
- * would mean two tools answering "is this account authenticated", one of them
13
- * depending on a store it does not own.
10
+ * ## No tool accepts a price
14
11
  *
15
- * The six long-running terraform tools (install/init/plan/apply/destroy/
16
- * refresh) run synchronously. Each call is bounded by the tool's own timeout,
17
- * not by any progress mechanism.
12
+ * `price_resources` writes `cost.json` from the rating API, and every figure in
13
+ * it came from an inquiry. The gate that protects an apply compares that record
14
+ * against the configuration, so its value rests on the numbers being quoted
15
+ * rather than supplied — a tool taking a hand-typed amount would be the one path
16
+ * by which a fabricated figure reached the record.
17
+ *
18
+ * ## No tool answers "am I authenticated"
19
+ *
20
+ * That lives in `aishell-credentials`, which owns the credential lifecycle and
21
+ * the form that collects AK/SK. A verify tool here would mean two tools
22
+ * answering the same question, one of them depending on a store it does not own.
23
+ *
24
+ * ## Long-running tools run synchronously
25
+ *
26
+ * install/init/plan/apply/destroy/refresh each run to completion within the
27
+ * call. The per-call budget is what bounds them; there is no progress channel
28
+ * to poll and no background handle to lose track of.
18
29
  */
19
30
  export declare function registerAllTools(registrar: ToolRegistrar): void;
20
31
  /**
@@ -24,9 +35,12 @@ export declare function registerAllTools(registrar: ToolRegistrar): void;
24
35
  */
25
36
  export declare const deploymentParam: z.ZodString;
26
37
  /**
27
- * Shared zod string schema for `dest` — the reference-data extraction
28
- * target, distinct from the deployment workspace (§3.2: "distinct from
29
- * the deployment workspace — this is where reference data is extracted").
38
+ * Shared zod string schema for `dest` — where reference data is extracted.
39
+ *
40
+ * A target of its own, not the deployment workspace: the terraform examples are
41
+ * material to read while writing a configuration, and dropping them into the
42
+ * workspace would put a few hundred `.tf` files where `configurationFiles`
43
+ * reads the deployment's own.
30
44
  */
31
45
  export declare const destParam: z.ZodString;
32
46
  //# sourceMappingURL=index.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
2
  /**
3
- * apiexplorer + openapi_request (§3.2).
3
+ * apiexplorer + openapi_request.
4
4
  *
5
5
  * apiexplorer wraps HuaweiCloud APIExplorer (the "API of APIs") — a dedicated
6
6
  * tool, NOT just openapi_request, because:
@@ -95,15 +95,25 @@ interface BodyField {
95
95
  /**
96
96
  * Extract fields from a JSON string using JSONPath (RFC 9535). Returns
97
97
  * undefined if the body is not valid JSON (caller falls back to returning
98
- * the raw body). Each path is evaluated via jsonpath-plus; a missing path
99
- * yields null, a single-match path yields the bare value (backward compat
100
- * with the old dot-path behavior), and a multi-match path (wildcards [*],
101
- * indices [N], recursive descent ..) yields an array of matches.
98
+ * the raw body).
102
99
  *
103
- * Upgraded from a hand-rolled dot-path walker that could not descend into
104
- * arrays — HuaweiCloud APIs return arrays (resource lists, bill details),
105
- * so account_balances[*].amount must work. jsonpath-plus is the RFC 9535
106
- * reference implementation for JS.
100
+ * ## Why JSONPath and not a dotted path walker
101
+ *
102
+ * HuaweiCloud API responses are arrays wherever there is a list — balances,
103
+ * bill entries, resource inventories — so `$.account_balances[*].amount` is
104
+ * the shape a caller actually wants, and a dotted walker cannot descend into
105
+ * one. `jsonpath-plus` is the RFC 9535 reference implementation for JS, and
106
+ * using it means the selector syntax a caller writes is the standard one.
107
+ *
108
+ * ## The unwrapping rule, and why it looks inconsistent
109
+ *
110
+ * A single match yields the bare value; anything else yields an array. The
111
+ * asymmetry is deliberate: `$.currency` names one thing, and returning
112
+ * `["CNY"]` for it would make every simple field awkward to use. A path with a
113
+ * wildcard, an index or a recursive descent asks for a SET — `[*]` over zero
114
+ * matches must yield `[]`, not `null`, or "no entries" becomes
115
+ * indistinguishable from "field absent". The match count decides, not the
116
+ * syntax, so both hold.
107
117
  */
108
118
  export declare function extractFields(jsonBody: string, fields: string[]): Array<{
109
119
  path: string;
@@ -0,0 +1,213 @@
1
+ /**
2
+ * `price_resources` — what the plan will actually cost.
3
+ *
4
+ * ## Why the plan, and not the `.tf`
5
+ *
6
+ * A `.tf` file is not a list of resources. It is a list of BLOCKS, and one
7
+ * block can become many resources:
8
+ *
9
+ * - `count = 3` is three instances, billed three times;
10
+ * - `for_each` is one per key;
11
+ * - `count = var.enabled ? 1 : 0` is one or none, depending on a value only
12
+ * terraform can compute;
13
+ * - `module "db"` hides its own resources entirely.
14
+ *
15
+ * Reading the blocks and multiplying by one understates every deployment that
16
+ * uses any of those, and the understatement is invisible: the total looks like
17
+ * a total. `terraform plan` has already resolved all of it, so it is the list
18
+ * this tool prices — `resource_changes[].type` for the classification and
19
+ * `change.after` for the values that decide the price.
20
+ *
21
+ * ## Why the classification is looked up and not tabulated
22
+ *
23
+ * BSS wants its own codes, and they do not follow from the terraform type (see
24
+ * `rating-map`). The service family is a short table; the resource type inside
25
+ * a service is catalogue data, so it is queried and the answer is verified by
26
+ * the price actually coming back.
27
+ *
28
+ * ## Why the region comes from the plan and not from configuration
29
+ *
30
+ * A price is per region, and a deployment may span several. The plan carries
31
+ * each resource's provider block, and that block's `region` is a constant when
32
+ * it was written as one — so the region is read per resource, never as a
33
+ * deployment-wide value. Verified: the same 40 GB volume costs 14.308 in one
34
+ * region and answers `CBC.99006006 Product not found` when the same product is
35
+ * asked of another region's project.
36
+ *
37
+ * A plan that names no region is reported as unpriced. Filling in a default
38
+ * would produce a number that is indistinguishable from a checked one, and
39
+ * wrong in a way nothing on screen contradicts.
40
+ *
41
+ * ## What it will not do
42
+ *
43
+ * It quotes nothing it cannot identify. A resource with no rating rule, a spec
44
+ * that came from a variable (so the plan does not know it), and a compute
45
+ * instance whose image does not name a platform are each reported as unpriced
46
+ * with the reason. A made-up number is indistinguishable from a checked one
47
+ * once it reaches `cost.json`, and a total that silently omits resources
48
+ * understates the bill.
49
+ *
50
+ * @module @huaweidevtools/aishell-dsh-deploy/tools/pricing
51
+ */
52
+ import type { ToolRegistrar } from '../types.ts';
53
+ /**
54
+ * Register `price_resources`.
55
+ *
56
+ * @param registrar - the capture surface this plugin's tools register into.
57
+ */
58
+ export declare function registerPricingTool(registrar: ToolRegistrar): void;
59
+ /** One resource as the plan describes it. */
60
+ export interface PlannedResource {
61
+ readonly address: string;
62
+ readonly type: string;
63
+ readonly action: string;
64
+ /** The attribute values terraform resolved, where it could. */
65
+ readonly after: Record<string, unknown>;
66
+ /**
67
+ * The region this resource is provisioned in.
68
+ *
69
+ * Per resource, not per deployment: a configuration may declare two provider
70
+ * blocks with different regions and point resources at either, and a price
71
+ * asked of the wrong region is a wrong price. Read from the provider block
72
+ * the resource names, falling back to the plugin's configured region when the
73
+ * block does not state one.
74
+ */
75
+ readonly region: string;
76
+ }
77
+ /**
78
+ * An address with every `[...]` index removed.
79
+ *
80
+ * `module.m["a"].huaweicloud_compute_instance.web[0]` becomes
81
+ * `module.m.huaweicloud_compute_instance.web`.
82
+ *
83
+ * @param address - a resource address.
84
+ * @returns the address the configuration block is keyed by.
85
+ */
86
+ export declare function unindexedAddress(address: string): string;
87
+ /**
88
+ * Which provider block each resource uses, by resource address.
89
+ *
90
+ * A module's resources are nested under that module in `root_module`, so the
91
+ * walk recurses — a deployment that puts its resources in modules would
92
+ * otherwise lose every region.
93
+ *
94
+ * @param configuration - the plan's `configuration` section.
95
+ * @returns resource address → `provider_config_key`.
96
+ */
97
+ export declare function resourceProviderKeys(configuration: unknown): Map<string, string>;
98
+ /**
99
+ * The region each provider configuration declares, keyed by its block name.
100
+ *
101
+ * A plan does not put a region on the resources — `after.region` is always
102
+ * pending, and `provider_name` is the same for every alias. What it DOES carry
103
+ * is `configuration`: one entry per provider block, with that block's `region`
104
+ * as a constant, and one `provider` reference on each resource naming which
105
+ * block it uses. Joining the two is how a resource's own region is recovered.
106
+ *
107
+ * A `region` given as an expression rather than a constant is left out: it
108
+ * resolves only when terraform runs, so the resource keeps the deployment's
109
+ * configured region instead of a guess.
110
+ *
111
+ * @param configuration - the plan's `configuration` section.
112
+ * @returns full provider name → region, for the blocks that name one.
113
+ */
114
+ export declare function providerRegions(configuration: unknown): Map<string, string>;
115
+ /**
116
+ * Whether a resource's action adds a monthly cost worth quoting.
117
+ *
118
+ * A `create` does, and so does a `replace` — terraform builds the new one, and
119
+ * the monthly figure is the price of what will exist. A `destroy` does not: the
120
+ * resource stops costing the moment it completes, and quoting it would add a
121
+ * recurring charge for something the plan removes. A `no-op` is already there
122
+ * and already in the user's bill, so quoting it double-counts.
123
+ *
124
+ * @param resource - one entry from the plan.
125
+ * @returns whether the resource will add a monthly cost.
126
+ */
127
+ export declare function carriesNewCost(resource: PlannedResource): boolean;
128
+ /**
129
+ * Whether a resource without a rating rule would plausibly cost money.
130
+ *
131
+ * The question decides only whether to REPORT it as unpriced. A VPC, a subnet
132
+ * and a security group are free; a cluster, a database or a bucket is not.
133
+ *
134
+ * ## Why the free list is enumerated rather than matched by prefix
135
+ *
136
+ * `huaweicloud_vpc` is the prefix of `huaweicloud_vpc_bandwidth` (dedicated
137
+ * bandwidth) and of `huaweicloud_vpc_eip`, both of which are billed monthly.
138
+ * A prefix test on `huaweicloud_vpc` therefore classifies paid resources as
139
+ * free and drops them from BOTH the quote and the unpriced report — a total
140
+ * that silently understates the bill, which is the one thing this tool is for.
141
+ * Verified against the provider's own type list.
142
+ *
143
+ * So the free types are written out. A type not listed here is reported as
144
+ * unpriced, which costs the reader one sentence and never a missing number.
145
+ *
146
+ * @param resource - the planned resource.
147
+ * @returns whether a missing price is worth reporting.
148
+ */
149
+ export declare function looksBillable(resource: PlannedResource): boolean;
150
+ /**
151
+ * One nested block's body from a plan's attribute map.
152
+ *
153
+ * A repeatable block appears as a list of bodies, and a single one as the body
154
+ * itself — the same two shapes the HCL parser produces, because both read
155
+ * terraform's own JSON.
156
+ *
157
+ * @param after - the resource's attribute map.
158
+ * @param name - the block's name.
159
+ * @returns the first body, or an empty map when the block is absent.
160
+ */
161
+ export declare function blockBody(after: Record<string, unknown>, name: string): Record<string, unknown>;
162
+ /** A number that may have arrived as a string. */
163
+ export declare function numberFrom(after: Record<string, unknown>, key: string): number | undefined;
164
+ /** The availability zone a resource sits in, from its own attributes. */
165
+ export declare function availabilityZoneOf(resource: PlannedResource): string | undefined;
166
+ /** Round to the cent, which is what a price is quoted in. */
167
+ export declare function round(amount: number): number;
168
+ /**
169
+ * Whether a cost record says "nothing to charge for" rather than "nothing was
170
+ * priced".
171
+ *
172
+ * The two look identical: both have an empty `items`. The apply gate has to
173
+ * tell them apart, because one is an approval and the other is a gap —
174
+ *
175
+ * - a network of VPCs, subnets, routes and security groups has no charge of
176
+ * its own, so an empty total is the correct figure and the deployment may
177
+ * proceed;
178
+ * - a deployment of databases whose specs came from variables has no quote
179
+ * either, and applying it spends money nobody has established a figure for.
180
+ *
181
+ * The discriminator is `unpriced`: every resource this tool could not answer is
182
+ * recorded there, with its reason. So an empty quote list with nothing
183
+ * unpriced is a plan that genuinely costs nothing.
184
+ *
185
+ * @param quoted - how many resources were priced.
186
+ * @param unpriced - how many could not be.
187
+ * @returns whether the record should carry `nothing_billable`.
188
+ */
189
+ export declare function statesNothingBillable(quoted: number, unpriced: number): boolean;
190
+ /**
191
+ * The monthly total of a set of quotes, and the currencies it spans.
192
+ *
193
+ * A total is only meaningful inside one currency. The rating API answers in the
194
+ * currency of the region's price list, and a deployment spanning regions can in
195
+ * principle draw from two — adding those figures would produce a number
196
+ * denominated in whichever came first, which reads exactly like a checked one.
197
+ *
198
+ * So the currencies are collected first, and a mixed set yields `total: null`
199
+ * rather than a sum. The caller reports the per-item figures with their own
200
+ * currencies and says they cannot be added.
201
+ *
202
+ * @param quotes - the priced resources.
203
+ * @returns the currencies present (sorted, so the report is stable) and the
204
+ * total, which is `null` when there is none to compute.
205
+ */
206
+ export declare function quoteTotal(quotes: readonly {
207
+ readonly monthly: number;
208
+ readonly currency: string;
209
+ }[]): {
210
+ readonly currencies: readonly string[];
211
+ readonly total: number | null;
212
+ };
213
+ //# sourceMappingURL=pricing.d.ts.map
@@ -1,6 +1,6 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
2
  /**
3
- * provider_schema (§3.2).
3
+ * provider_schema.
4
4
  *
5
5
  * Runs `terraform providers schema -json` and extracts the huaweicloud
6
6
  * provider's schema. The full output is ~6MB (thousands of resource and
@@ -0,0 +1,41 @@
1
+ /**
2
+ * `lookup_specs` — what the region offers, and whether the design asks for it.
3
+ *
4
+ * ## The gap it fills
5
+ *
6
+ * A `.tf` names a flavour and an image by ID, and `terraform validate` accepts
7
+ * any string there. So a design with an invented flavour is schema-valid,
8
+ * validates clean, gets drawn, gets priced, gets approved — and fails at apply,
9
+ * on the first instance, on a value nobody could have checked.
10
+ *
11
+ * This tool answers the question a person actually has at that moment: "is
12
+ * `c7.large.2` a thing this region sells, in the zone I put it in, and does the
13
+ * image fit on it?"
14
+ *
15
+ * ## Two modes, because there are two moments
16
+ *
17
+ * - **No `deployment`**: list what the region offers. This is what the model
18
+ * needs BEFORE writing `.tf`, because `flavor_id` and `image_id` are UUIDs and
19
+ * names it cannot invent.
20
+ * - **With `deployment`**: read the `.tf`, and check every flavour and image it
21
+ * names against the catalogue. This is the check nothing else performs:
22
+ * `terraform validate` accepts any string for `flavor_id`, so a design naming
23
+ * a flavour the region does not sell passes validation and fails at apply.
24
+ *
25
+ * ## What it reports, and what it does not
26
+ *
27
+ * It reports absence and mismatch. It does not judge suitability — whether
28
+ * 4 vCPU is enough for the workload is the user's call, and a tool that
29
+ * guessed would be overstepping. The numbers are returned so the person can
30
+ * decide.
31
+ *
32
+ * @module @huaweidevtools/aishell-dsh-deploy/tools/specs
33
+ */
34
+ import type { ToolRegistrar } from '../types.ts';
35
+ /**
36
+ * Register `lookup_specs`.
37
+ *
38
+ * @param registrar - the capture surface this plugin's tools register into.
39
+ */
40
+ export declare function registerSpecsTool(registrar: ToolRegistrar): void;
41
+ //# sourceMappingURL=specs.d.ts.map
@@ -1,32 +1,34 @@
1
1
  import type { ToolRegistrar } from "../types.js";
2
- /** Shared terraform runner: resolve env, then spawn. */
3
- export interface TerraformResult {
4
- exitCode: number;
5
- stdout: string;
6
- stderr: string;
7
- /** True if stdout was truncated at MAX_OUTPUT_BYTES (output incomplete). */
8
- stdoutTruncated?: boolean;
9
- /** True if stderr was truncated at MAX_OUTPUT_BYTES. */
10
- stderrTruncated?: boolean;
11
- }
12
- export declare function runTerraform(cwd: string, args: string[], extraEnv?: string[]): Promise<TerraformResult>;
13
2
  /** Register all 9 terraform tools. */
14
3
  export declare function registerTerraformTools(registrar: ToolRegistrar): void;
15
4
  /**
16
- * Derive create/change/destroy counts from `terraform show -json <plan>`
17
- * resource_changes — the authoritative, version-independent source.
5
+ * One resource's full state, by terraform address.
18
6
  *
19
- * terraform 1.9+ changed the `plan -json` stdout summary line to
20
- * type:"change_summary" (from type:"summary"), so parsePlanSummary returns 0.
21
- * The show -json output's resource_changes[].change.actions is stable across
22
- * versions: actions is an array like ["create"], ["update"], ["delete"],
23
- * ["no-op"], or composite like ["create","delete"] (replace). We take the
24
- * first action as the primary — same mapping convention as terraform's own
25
- * tfjson (planFromJSON actionFromTFJSON).
7
+ * The address is compared exactly, and in the form terraform writes it:
8
+ * `module.net.huaweicloud_vpc.prod` for a module, `…web[0]` for a counted one.
9
+ * A plain block address also answers for a resource declared with `count = 1`
10
+ * only when the state spells it that way — nothing is guessed, because a
11
+ * substring match would return a resource the caller did not name.
12
+ *
13
+ * @param stateJson - the parsed `terraform show -json` output.
14
+ * @param address - the address to select.
15
+ * @returns that resource's values, or `undefined` when it is not in the state.
16
+ */
17
+ export declare function stateResource(stateJson: unknown, address: string): unknown;
18
+ /**
19
+ * Every resource in a state document, as the pair a reader acts on.
20
+ *
21
+ * The address is what `terraform_import`, `-target` and `terraform_destroy`
22
+ * all take, so it is the thing a caller needs; the type is what a reader
23
+ * groups by. The attributes are deliberately absent — they are the bulk, and
24
+ * `address` returns them for the one resource asked about.
25
+ *
26
+ * @param stateJson - the parsed `terraform show -json` output.
27
+ * @returns one entry per resource, in state order.
26
28
  */
27
- export declare function summaryFromPlanJson(planJson: unknown): {
28
- create: number;
29
- change: number;
30
- destroy: number;
31
- };
29
+ export declare function stateInventory(stateJson: unknown): {
30
+ readonly address: string;
31
+ readonly type: string;
32
+ readonly module?: string;
33
+ }[];
32
34
  //# sourceMappingURL=terraform.d.ts.map