@huaweidevtools/aishell-dsh-deploy 0.0.15 → 0.0.17

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 (60) hide show
  1. package/README.md +28 -9
  2. package/cordis.patch.yml +12 -3
  3. package/lib/data/permission-registry.json +1 -1
  4. package/lib/index.js +6163 -1474
  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 +20 -5
  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-design.d.ts +60 -0
  13. package/lib/types/d2-engine.d.ts +111 -0
  14. package/lib/types/d2-inventory.d.ts +54 -0
  15. package/lib/types/data-paths.d.ts +10 -0
  16. package/lib/types/deployment-state.d.ts +90 -13
  17. package/lib/types/existing-topology.d.ts +154 -0
  18. package/lib/types/existing.d.ts +100 -0
  19. package/lib/types/gates/cost_gate.d.ts +38 -16
  20. package/lib/types/gates/credential_gate.d.ts +29 -3
  21. package/lib/types/gates/design_gate.d.ts +72 -0
  22. package/lib/types/gates/mirror.d.ts +1 -1
  23. package/lib/types/gates/plan_gate.d.ts +116 -0
  24. package/lib/types/gates/provider_installed.d.ts +32 -0
  25. package/lib/types/gates/terraform_env.d.ts +16 -3
  26. package/lib/types/hcl.d.ts +176 -0
  27. package/lib/types/index.d.ts +18 -4
  28. package/lib/types/inventory-subnets.d.ts +78 -0
  29. package/lib/types/network-checks.d.ts +67 -0
  30. package/lib/types/paths.d.ts +51 -0
  31. package/lib/types/permission/gate.d.ts +6 -6
  32. package/lib/types/permission/registry.d.ts +11 -0
  33. package/lib/types/plan.d.ts +68 -0
  34. package/lib/types/projects.d.ts +40 -0
  35. package/lib/types/prompt.d.ts +5 -4
  36. package/lib/types/rating-map.d.ts +132 -0
  37. package/lib/types/security-groups.d.ts +16 -23
  38. package/lib/types/terraform-run.d.ts +32 -0
  39. package/lib/types/tools/annotations.d.ts +1 -1
  40. package/lib/types/tools/balance_summary.d.ts +1 -1
  41. package/lib/types/tools/deployment.d.ts +3 -3
  42. package/lib/types/tools/design.d.ts +54 -0
  43. package/lib/types/tools/errors.d.ts +22 -4
  44. package/lib/types/tools/examples.d.ts +1 -1
  45. package/lib/types/tools/existing_resources.d.ts +1 -1
  46. package/lib/types/tools/index.d.ts +26 -12
  47. package/lib/types/tools/openapi.d.ts +19 -9
  48. package/lib/types/tools/pricing.d.ts +213 -0
  49. package/lib/types/tools/provider_schema.d.ts +1 -1
  50. package/lib/types/tools/specs.d.ts +41 -0
  51. package/lib/types/tools/terraform.d.ts +27 -25
  52. package/lib/types/topology.d.ts +232 -0
  53. package/lib/types/types.d.ts +29 -4
  54. package/lib/types/utils/hash.d.ts +15 -5
  55. package/package.json +4 -2
  56. package/lib/types/gates/networking_gate.d.ts +0 -9
  57. package/lib/types/schemas/cost.d.ts +0 -108
  58. package/lib/types/schemas/networking.d.ts +0 -115
  59. package/lib/types/tools/cost.d.ts +0 -16
  60. package/lib/types/tools/networking.d.ts +0 -13
@@ -0,0 +1,67 @@
1
+ /**
2
+ * The design checks the provider's own validation does not perform.
3
+ *
4
+ * ## Why these exist
5
+ *
6
+ * `terraform validate` checks each block against the provider's schema and
7
+ * settles every reference. It does NOT check the properties that hold ACROSS
8
+ * blocks — the provider reports `Success!` for all of the following:
9
+ *
10
+ * - two subnets in one VPC with the same CIDR
11
+ * - a subnet whose CIDR falls outside its VPC
12
+ * - a `gateway_ip` outside its own subnet
13
+ * - a security-group rule opening SSH to `0.0.0.0/0`
14
+ *
15
+ * Each of those produces a working `apply` and a network that does not do what
16
+ * its author meant. Nothing in terraform's toolchain reports them at plan time
17
+ * either: they are facts about the assembled network, and only the assembly
18
+ * knows them.
19
+ *
20
+ * ## Why findings and not errors
21
+ *
22
+ * A finding is reported and the deployment continues. Refusing would be wrong
23
+ * in two directions. Some are legitimate: a peering or a load balancer
24
+ * requires its own subnet, and a bastion host may genuinely need SSH from
25
+ * anywhere. And the model cannot repair what it is not told about — an error
26
+ * that stops the tool before it writes the diagram leaves the reader with no
27
+ * picture and no explanation. So the diagram is produced, and the problems
28
+ * ride beside it.
29
+ *
30
+ * @module @huaweidevtools/aishell-dsh-deploy/network-checks
31
+ */
32
+ import type { Finding } from './topology.ts';
33
+ import type { ResourceBlock } from './hcl.ts';
34
+ import type { ExistingResource } from './existing.ts';
35
+ /** One IPv4 CIDR, as the numbers it denotes. */
36
+ interface Cidr {
37
+ /** The address as a 32-bit unsigned integer. */
38
+ readonly base: number;
39
+ /** How many of the high bits are the network. */
40
+ readonly prefix: number;
41
+ }
42
+ /**
43
+ * Parse a dotted-quad CIDR into its network number and prefix length.
44
+ *
45
+ * @param text - a value such as `10.0.1.0/24`.
46
+ * @returns the parsed CIDR, or `undefined` when the text is not one.
47
+ */
48
+ export declare function parseCidr(text: string): Cidr | undefined;
49
+ /**
50
+ * Every design problem the configuration contains, most severe first.
51
+ *
52
+ * Two families, and they need different inputs. The security-group checks read
53
+ * the configuration alone — a rule's exposure is a fact about that rule. The
54
+ * address-plan checks need the account too: whether a new subnet collides with
55
+ * one already deployed cannot be answered from the file that does not mention
56
+ * it.
57
+ *
58
+ * @param blocks - the deployment's resource blocks.
59
+ * @param existing - the resources the caller reported as already present.
60
+ * @param byAddress - every known node, by terraform address, as the topology
61
+ * derived it. Only its keys are read, so the node ids a finding names agree
62
+ * with the ones a reader can find in the recorded deployment.
63
+ * @returns the findings, most severe first, each naming its resources.
64
+ */
65
+ export declare function findProblems(blocks: readonly ResourceBlock[], byAddress: ReadonlyMap<string, unknown>, existing?: readonly ExistingResource[]): Finding[];
66
+ export {};
67
+ //# sourceMappingURL=network-checks.d.ts.map
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The absolute directory a caller's directory argument names.
3
+ *
4
+ * ## The problem this exists for
5
+ *
6
+ * Every tool in this plugin takes a directory. A model supplies it, and a model
7
+ * supplies what it just said: after `create_deployment({deployment:
8
+ * "huawei-topology"})` the next call passes `"huawei-topology"` again, because
9
+ * that is the name it has been using. A relative path is not wrong — it is how
10
+ * people talk about directories.
11
+ *
12
+ * What is wrong is leaving its meaning to Node. A relative path passed to
13
+ * `readFile` or `spawn` resolves against `process.cwd()`: the directory the
14
+ * host was launched from. That has nothing to do with the working directory the
15
+ * person chose for this session. Two tools then disagree — `write` saving to
16
+ * the session directory and `terraform_init` reading from the launch directory
17
+ * — and the symptom is a workspace nobody can find, which reads like a bug in
18
+ * whichever tool reported it first.
19
+ *
20
+ * So the anchor is explicit: the session's working directory, which is what
21
+ * every filesystem tool in the product uses and what a person means by "here".
22
+ *
23
+ * The rule is stated once here rather than per argument name, because it is a
24
+ * fact about directories, not about `deployment` in particular: `dest` is the
25
+ * same kind of value and had the same defect.
26
+ *
27
+ * ## Why there is no fallback
28
+ *
29
+ * When the host offers no session directory, a relative path has no correct
30
+ * meaning. Falling back to `process.cwd()` would restore the exact
31
+ * disagreement above, silently, for every call. The tools therefore ask for an
32
+ * absolute path in that case and say why — a caller can comply, and nobody
33
+ * writes somewhere unintended.
34
+ *
35
+ * An absolute path needs none of this: it already means one thing.
36
+ *
37
+ * @module @huaweidevtools/aishell-dsh-deploy/paths
38
+ */
39
+ import type { ToolContext } from './types.ts';
40
+ /**
41
+ * The absolute directory a directory argument names.
42
+ *
43
+ * @param given - the path the caller gave, relative or absolute.
44
+ * @param context - the call's context, carrying the session directory when the
45
+ * host provides one.
46
+ * @returns the absolute path.
47
+ * @throws when the path is relative and there is no session directory to anchor
48
+ * it — the caller gets a remedy, not a directory chosen for them.
49
+ */
50
+ export declare function anchorPath(given: string, context: ToolContext | undefined): string;
51
+ //# sourceMappingURL=paths.d.ts.map
@@ -12,12 +12,12 @@
12
12
  * including the arbitrary method/URL that `openapi_request` accepts, without
13
13
  * each tool having to remember to ask.
14
14
  *
15
- * IAM credential verification used to be one of those callers. It moved to the
16
- * shared `credentials-store/verify` module when `auth` moved to
17
- * `aishell-credentials`, so it is no longer gated here — correctly: verifying a
18
- * credential the person just supplied is not a cloud mutation, and a session
19
- * in read-only mode must still be able to answer "are these credentials
20
- * valid?" before anything is planned.
15
+ * Credential verification is deliberately NOT one of those callers: it lives in
16
+ * the shared `credentials-store/verify` module, owned by `aishell-credentials`
17
+ * alongside the form that collects the pair. Verifying a credential the person
18
+ * just supplied is not a cloud mutation, and a session in read-only mode must
19
+ * still be able to answer "are these credentials valid?" before anything is
20
+ * planned.
21
21
  *
22
22
  * The check applies to every call, including any that pass credentials
23
23
  * explicitly. Keying an exemption on whether a caller happened to pass a
@@ -57,6 +57,17 @@
57
57
  * not from the cache. A burst of `ListApis` calls during measurement returned
58
58
  * HTTP 429.
59
59
  *
60
+ * ## Supplemented operations
61
+ *
62
+ * Some reads are missing from the cache and cannot be fetched into it — BSS is
63
+ * the case that matters, since `ListApis` answers zero entries for both its
64
+ * editions. The builder carries a `SUPPLEMENTS` list for those: each entry names
65
+ * the operation and the evidence that it is a query, so the addition is
66
+ * reviewable rather than an unexplained line in the artifact.
67
+ *
68
+ * A supplemented path still loses to the write-wins rule, so nothing a
69
+ * supplement adds can admit an operation the metadata classifies as a mutation.
70
+ *
60
71
  * ## Why the host's first label is the service key
61
72
  *
62
73
  * The service directory in the metadata is not recoverable from a request —
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Reading `terraform show -json` into the changes a person has to approve.
3
+ *
4
+ * ## Why this is not the raw plan
5
+ *
6
+ * A plan for a small deployment is a few kilobytes; one for a real network runs
7
+ * to megabytes, and almost all of it is provider defaults for attributes nobody
8
+ * asked about. Handing that to the model spends its context on values the user
9
+ * never chose, and buries the handful that matter — which resource is created,
10
+ * replaced or destroyed.
11
+ *
12
+ * So the plan is read into the two things an approval turns on:
13
+ *
14
+ * - **What happens to each resource** — create, update, replace, destroy —
15
+ * keyed by its terraform address.
16
+ * - **Which attributes change** — the names only, for an update. The values
17
+ * are in the plan; a reader who needs them can look, and a model that gets
18
+ * the names knows where to look.
19
+ *
20
+ * ## Why replacement is its own action
21
+ *
22
+ * `actions: ["delete", "create"]` means terraform will DESTROY and rebuild the
23
+ * resource. Reported as "update" — which is what a reader who only saw "something
24
+ * changes" would conclude — it hides the one fact that matters: the data on that
25
+ * volume or database is going away. Terraform marks it; this module keeps that
26
+ * mark.
27
+ *
28
+ * @module @huaweidevtools/aishell-dsh-deploy/plan
29
+ */
30
+ /** What terraform will do to one resource. */
31
+ export type ChangeAction = 'create' | 'update' | 'replace' | 'destroy' | 'read' | 'no-op';
32
+ /** One resource's entry in the plan. */
33
+ export interface PlannedResource {
34
+ /** The terraform address, e.g. `huaweicloud_compute_instance.web`. */
35
+ readonly address: string;
36
+ readonly action: ChangeAction;
37
+ /**
38
+ * What forces a replacement, when there is one — terraform attributes the
39
+ * delete to specific arguments (`~ image_id`, `-/+ force_new`). Empty for
40
+ * anything but a replace.
41
+ */
42
+ readonly replacedBecause: readonly string[];
43
+ /** Attribute names that change, for an update. Empty otherwise. */
44
+ readonly changes: readonly string[];
45
+ }
46
+ /** The plan, reduced to what approval needs. */
47
+ export interface PlanSummary {
48
+ readonly counts: {
49
+ readonly create: number;
50
+ readonly change: number;
51
+ readonly destroy: number;
52
+ };
53
+ /** Every resource the plan touches, in the order terraform listed them. */
54
+ readonly resources: readonly PlannedResource[];
55
+ /** Terraform's own output changes, by name. */
56
+ readonly outputs: readonly {
57
+ readonly name: string;
58
+ readonly action: ChangeAction;
59
+ }[];
60
+ }
61
+ /**
62
+ * Read a plan into its summary.
63
+ *
64
+ * @param planJson - the parsed `terraform show -json` document.
65
+ * @returns the summary, or `undefined` when the document is not a plan.
66
+ */
67
+ export declare function summarizePlan(planJson: unknown): PlanSummary | undefined;
68
+ //# sourceMappingURL=plan.d.ts.map
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Where the account's projects are, by region.
3
+ *
4
+ * ## Why this is one module
5
+ *
6
+ * A region-scoped HuaweiCloud API puts a project id in the path, and the id is
7
+ * not the account id: one account has one project per region, and pairing a
8
+ * project with another region's host answers HTTP 400. Three callers need that
9
+ * mapping — the price quote, the catalogue lookup, and the subnet listing that
10
+ * completes an inventory — and three private copies of the same IAM call would
11
+ * be three places to keep in step.
12
+ *
13
+ * ## The endpoint is global
14
+ *
15
+ * `iam.myhuaweicloud.com` (no region prefix) answers with every project the
16
+ * account has, in every region, in one response. So one call serves a plan that
17
+ * spans several regions, and the result is worth keeping for the life of one
18
+ * tool call.
19
+ *
20
+ * @module @huaweidevtools/aishell-dsh-deploy/projects
21
+ */
22
+ import type { Credentials } from './credentials.ts';
23
+ /**
24
+ * Every project the account has, keyed by region name.
25
+ *
26
+ * @param credentials - the pair to sign with.
27
+ * @returns region name → project id.
28
+ * @throws when IAM cannot answer, with its own reason.
29
+ */
30
+ export declare function projectMap(credentials: Credentials): Promise<Map<string, string>>;
31
+ /**
32
+ * The project id for one region, or a message naming what the account does have.
33
+ *
34
+ * @param projects - the map from {@link projectMap}.
35
+ * @param region - the region a request is going to.
36
+ * @returns the project id.
37
+ * @throws when the account has no project there, listing the regions it does.
38
+ */
39
+ export declare function projectIn(projects: ReadonlyMap<string, string>, region: string): string;
40
+ //# sourceMappingURL=projects.d.ts.map
@@ -3,11 +3,12 @@
3
3
  *
4
4
  * ## Why a prompt section and not just tool descriptions
5
5
  *
6
- * Seventeen tools each say what they do. None of them says what *order* to
6
+ * Eighteen tools each say what they do. None of them says what *order* to
7
7
  * call them in, or where a person has to approve before the next step runs.
8
8
  * That knowledge is the difference between a model that can drive a deployment
9
- * and one that calls `terraform_apply` on a directory with no `networking.json`
10
- * and no cost estimate, then reports the resulting gate refusal as a bug.
9
+ * and one that calls `terraform_apply` on a directory whose network design was
10
+ * never checked and which has no cost estimate, then reports the resulting gate
11
+ * refusal as a bug.
11
12
  *
12
13
  * The section also carries the constraint the tools cannot express: several
13
14
  * steps require explicit user consent before proceeding, and a tool description
@@ -45,7 +46,7 @@ export declare const WORKFLOW_SECTION_NAME = "aishell:deploy-workflow";
45
46
  * Every tool name appears as the model sees it, `aishell__<name>`, so a model
46
47
  * can copy it straight into a call.
47
48
  */
48
- export declare const DEPLOY_WORKFLOW = "Huawei Cloud work goes through the aishell__ tools below, not through shell commands. They carry the safety gates (a plaintext-credential scan, a cost-hash check, a networking check) that a bare `terraform` invocation bypasses.\n\n## Deployment flow\n\nSteps marked \u2605 require the user's explicit agreement before you continue.\n\n1. aishell__auth \u2014 verify the account and list its projects. Each project's `name` is a region; a region-scoped API (one whose path contains `{project_id}`) needs the project id from here.\n2. aishell__create_deployment \u2014 create or reuse the deployment workspace.\n3. aishell__apiexplorer \u2014 look up API definitions. With no arguments it lists every service; with a product it lists that service's APIs; with an API name it returns the contract (`compact: true` for the condensed form, `regions: true` for available regions and project ids).\n aishell__terraform_examples_export \u2014 write `.tf` examples to a directory. That directory is a reference target, not the deployment workspace.\n4. aishell__update_networking \u2014 design the topology: VPC, subnets, routes, security groups, plus the EIP/NAT/ELB objects and the component list.\n \u2605 Show the topology to the user and get explicit agreement before writing it. Include VPC, subnet CIDRs, security-group rules and how the network objects connect; prefer rendering it as HTML. If the user asks for changes, revise until they accept, then call the tool again. Do not start any later step before that.\n \u2605 Opening SSH to 0.0.0.0/0 is a risk. Tell the user to restrict the source range.\n5. aishell__list_existing_resources \u2014 inventory what already exists that could be reused. The response also carries a balance summary (balance and vouchers).\n6. Decide per component: reuse or create.\n - Reuse: the spec and charging are fixed by the existing resource. Write the resource block, then aishell__terraform_import to bring it into state.\n - Create: choose a spec and a charging mode, querying available flavors and images with aishell__openapi_request.\n7. aishell__openapi_request(\"GET\", <BSS price API>) \u2014 fetch the real price for the new resources. Use the `fields` parameter to keep large responses out of context.\n8. aishell__update_cost \u2014 write `cost.json`: spec, charging, price, and whether each item is reused or new.\n \u2605 Show the cost breakdown before continuing: what is reused, what is bought, each item's spec and charging mode, and the new monthly total.\n9. Report the balance summary from step 5: balance and vouchers. Vouchers are applied automatically at the account level (voucher, then cash coupon, then balance) with nothing to configure in `.tf`. If vouchers exist, say the actual monthly increase may come in below the `cost.json` estimate. Check each voucher's `expire_time` and warn about any nearing expiry.\n10. Write the `.tf` files from `cost.json` and `networking.json`. Credentials come from the environment; never write `access_key`, `secret_key` or `security_token` into a `.tf` file.\n11. aishell__terraform_init \u2014 the gate here scans for plaintext credentials and refuses if it finds any.\n12. aishell__provider_schema \u2014 the argument contract for a resource type, when you need it.\n13. aishell__terraform_plan \u2014 preview the change.\n \u2605 Show the plan summary (what will be created, changed and destroyed) and the security-group rules before applying.\n14. aishell__terraform_apply \u2014 run it. Four gates run first: `networking.json` exists, `cost.json` exists, its `tf_hash` still matches the `.tf` files, and no plaintext credential is present.\n\n## Destroying and resynchronising\n\n- aishell__terraform_destroy removes everything terraform manages in that deployment. It refuses a non-empty tfstate only after the credential scan passes.\n \u2605 List the resources that will be destroyed and get explicit agreement first. Destruction cannot be undone.\n If the deployment also imported existing resources, destroy only what this deployment created with `target: [...]` and leave the imported ones. Call aishell__terraform_state first to list the addresses and let the user choose.\n- aishell__terraform_refresh \u2014 when the cloud changed outside terraform (edited in the console, a resource deleted by hand), refresh state and then plan to see the difference.\n- aishell__terraform_state \u2014 read state: resource addresses, attributes, security-group rules.\n\n## Hard lines\n\n- Cloud resources are created and destroyed **only** through aishell__terraform_apply and aishell__terraform_destroy. Do not use `POST`/`PUT`/`DELETE` on aishell__openapi_request to create or destroy resources unless the user explicitly asks for the API route and understands the consequences: it skips the cost gate, never enters tfstate, and leaves no trace.\n- Before applying or destroying, name the resources involved and get the user's explicit agreement. Never run these silently.\n- A `.tf` file must never contain a plaintext `access_key`, `secret_key` or `security_token`. The scan runs before init and apply and refuses the run.\n- `cost.json` must exist and its `tf_hash` must match before apply. Editing a `.tf` file invalidates it; recompute the cost.\n- Other `POST`/`DELETE` calls (issuing a voucher, adjusting a quota \u2014 not resource lifecycle) do run, and return a warning. Pass that warning to the user.\n\n## Mainland region filing\n\nIn mainland regions (cn-north-1, cn-north-4, cn-east-3 and others), serving web traffic on ports 80/443 requires ICP filing. Traffic is blocked without it. If the user wants a web port, ask about their filing status first.\n\n## Typical requests\n\n- \"How many ECS instances do I have?\" \u2192 aishell__list_existing_resources with `service: \"ecs\"`\n- \"What did I spend this month?\" \u2192 aishell__openapi_request(\"GET\", <BSS bill API>)\n- \"How many vouchers do I have?\" \u2192 the `balance_summary` field of aishell__list_existing_resources\n- \"What arguments does this resource take?\" \u2192 aishell__provider_schema(deployment, \"huaweicloud_compute_instance\")\n- \"Tear this deployment down\" \u2192 aishell__terraform_destroy, after listing the resources for confirmation\n- \"The cloud changed, resync\" \u2192 aishell__terraform_refresh, then aishell__terraform_plan for the difference\n- \"What is deployed right now?\" \u2192 aishell__terraform_state\n- \"Bring this existing instance under management\" \u2192 write the resource block, then aishell__terraform_import\n\n## Product documentation\n\nFor what a Huawei Cloud product *is* \u2014 features, quotas, limits, charging models \u2014 read the index at https://support.huaweicloud.com/llms.txt. It lists every product's documentation entry point by category; read it to locate the product, then that product's own `llms.txt` for detail.\n\nDo not answer questions about a product's feature boundaries, quotas or charging rules from memory \u2014 they change between releases. For API contracts use aishell__apiexplorer; for what exists in the account use aishell__list_existing_resources; this index is for \"what is this product and what are its limits\".";
49
+ export declare const DEPLOY_WORKFLOW = "Huawei Cloud work goes through the aishell__ tools below, not through shell commands. They carry the safety gates (a plaintext-credential scan, a cost-hash check, a networking check) that a bare `terraform` invocation bypasses.\n\n## Deployment flow\n\nSteps marked \u2605 require the user's explicit agreement before you continue.\n\n1. aishell__auth \u2014 verify the account and list its projects. Each project's `name` is a region; a region-scoped API (one whose path contains `{project_id}`) needs the project id from here.\n2. aishell__list_existing_resources \u2014 what the account already has. This is the first question, not the fifth: a design for an account that already runs a VPC is mostly \"what can be reused and what must not collide\", and nothing in the .tf can tell you that. Drill into the services the user's request is about (`service: \"vpc\"`, then `\"ecs\"` and so on); the summary alone is counts.\n aishell__create_deployment \u2014 create or reuse the deployment workspace.\n3. aishell__terraform_install \u2014 ensure a terraform binary is available: `terraform_path` if the user has one, else PATH, else the host cache, else a download from `binary_mirrors`. Idempotent, so calling it when one is already present costs nothing \u2014 call it before `terraform_init`, not after it fails with \"terraform not found\".\n aishell__terraform_init \u2014 install the provider. This comes BEFORE the design check, not after: `terraform validate` needs the provider to have an opinion about a configuration, and without it `validate_design` reports \"not validated\" \u2014 a design nobody checked against the provider schema. The gate here also scans for plaintext credentials and refuses if it finds any.\n aishell__apiexplorer \u2014 look up API definitions. With no arguments it lists every service; with a product it lists that service's APIs; with an API name it returns the contract (`compact: true` for the condensed form, `regions: true` for available regions and project ids).\n aishell__terraform_examples_export \u2014 write `.tf` examples to a directory. That directory is a reference target, not the deployment workspace.\n4. Write the network `.tf`: the VPC, its subnets, the security groups and their rules, and any gateway or load balancer. This stage needs no flavour, no image and no resource id \u2014 the network design is what decides those, not the other way round \u2014 so it needs no cloud credentials either.\n Write the provider block with the region as a LITERAL: `provider \"huaweicloud\" { region = \"cn-north-4\" }`. Nothing else carries it. There is no plugin-wide default region, so a provider block without one is a configuration terraform refuses, and a region given as a variable is one the price inquiry cannot read. A deployment may declare several provider blocks with different regions and point resources at each with `provider = huaweicloud.<alias>`; the price inquiry prices each resource in its own region.\n aishell__validate_design \u2014 check that design and draw it. It runs `terraform validate` when the provider is installed, then reports what terraform cannot: overlapping subnet CIDRs, a subnet outside its VPC, a gateway_ip outside its subnet, and rules open to 0.0.0.0/0 on administrative or database ports. It writes `topology.svg` beside the configuration and returns its absolute path.\n The drawing is a VIEW, not an inventory. It shows the network and what it carries; a configuration also declares alarm rules, log groups, backups and key pairs, and those come back counted under `omitted` and are not drawn. If `omitted` is non-empty, say so \u2014 do not let the picture read as the whole file. Connections between VPCs (a peering, a VPCEP endpoint, a route) are drawn as LABELLED EDGES rather than boxes, and listed under `connections`; an entry with `unresolved` means the far network is not declared here, which is normal for an endpoint service published by another account.\n Pass the resources from step 2 that this design is about as `existing`, so the picture shows what is already deployed (dashed) next to what would be created. Two things depend on it. An existing subnet is what a new subnet can COLLIDE with, and that collision is invisible to a check that only reads the .tf. And a .tf that reuses a VPC it does not declare (`vpc_id = huaweicloud_vpc.prod.id` with no `huaweicloud_vpc.prod` block) needs `address: \"huaweicloud_vpc.prod\"` on that existing resource, or the subnet is drawn at the root as if it created a new VPC.\n \u2605 Show the diagram and the findings, and get explicit agreement before going further. Put the picture in your reply as `![topology](<the absolute path it returned>)`. If the user asks for changes, edit the `.tf`, call validate_design again, and show the new picture. Do not start any later step before they accept.\n \u2605 Opening SSH to 0.0.0.0/0 is a risk. The tool reports it; still raise it in your own words and ask the user to restrict the source range. A finding is information, not permission.\n5. Report the balance summary from the step-2 inventory: balance and vouchers.\n6. Decide per component: reuse or create.\n - Reuse: the spec and charging are fixed by the existing resource. Write the resource block, then aishell__terraform_import to bring it into state. This needs the provider installed, which step 3 did.\n \u2605 An import does NOT check that the block you wrote matches the resource that exists \u2014 it records what the cloud holds. Call aishell__terraform_plan straight after each import and show the user the diff. A non-empty diff means applying would CHANGE a resource they asked you to leave alone, possibly by replacing it. Fix the block until the plan shows no change, or get explicit agreement that the change is wanted.\n - Create: aishell__lookup_specs takes `region` and `availability_zone` and lists the flavours and images that region actually sells there, with each flavour's vCPUs, memory and disk and each image's OS and minimums. Both are required: a flavour exists per zone in a region, and a catalogue listed for one region says nothing about another. Pass the region from the provider block. Call it BEFORE writing the resource block: `flavor_id` and `image_id` are values only the region knows, and an invented one passes `terraform validate` (it checks only that the value is a string) and fails at apply.\n Pick a flavour and an image whose minimum disk and memory the flavour can meet, and state the choice to the user \u2014 this is the decision the price hangs on.\n7. Add the compute, database and other resources to the same `.tf` files, from the design agreed in step 4 and the flavours chosen in step 6. Credentials come from the environment; never write `access_key`, `secret_key` or `security_token` into a `.tf` file.\n8. aishell__provider_schema \u2014 the argument contract for a resource type, when you need it.\n9. aishell__terraform_plan \u2014 compute the change and save it to `plan.tfplan`. It returns one entry per resource: the action (create / update / **replace** / destroy), the attribute names an update touches, and \u2014 for a replace \u2014 what forces the rebuild. It also returns the security-group rules the change would create.\n \u2605 Show the user every resource with its action, and the security-group rules. A **replace** is not an update: terraform destroys the resource and builds it again, so the data on that disk or database is gone. Call it out by name and say what forces it. Do not proceed on \"a few things change\" \u2014 name them. Do not describe the plan as reversible.\n10. aishell__price_resources \u2014 read the SAVED PLAN and quote every priceable resource against this account's own on-demand prices, then write `cost.json`. Prices come after the plan, not before, because the plan is the real list: a block with `count = 3` is three instances, `for_each` is one per key, and a module's resources are visible \u2014 none of which the .tf files show. Each figure is a month (730 hours), with the list price and the moment of the inquiry.\n It prices compute instances (Linux and Windows bill separately, from the image), RDS instances, DCS instances, EVS volumes and EIPs. Do NOT walk the .tf yourself to estimate the rest: it reports exactly which resources it could not price and why, and a spec that came from a variable cannot be priced at all. Say which ones are unpriced \u2014 a total that silently omits them understates the bill.\n11. \u2605 Report the cost before applying: each resource's spec, its monthly figure, the total, and which resources are unpriced and why, plus the balance and vouchers from step 5. Get the user's explicit agreement on the specification and the cost.\n Vouchers are applied automatically at the account level (voucher, then cash coupon, then balance) with nothing to configure in `.tf`. Say so: if vouchers exist, the actual monthly increase may come in below the quoted figure. Check each voucher's `expire_time` and warn about any nearing expiry.\n12. aishell__terraform_apply \u2014 run it. Five gates run first: the design was checked by aishell__validate_design, the cost was quoted by aishell__price_resources, and terraform_plan computed the saved plan \u2014 each of the three recorded against a digest of the configuration, and each refusing when the `.tf` has changed since. The fifth is the credential scan. Then it applies THAT saved plan rather than re-planning, so the changes executed are exactly the ones shown in step 9. ANY edit after validating, planning or pricing invalidates all three \u2014 call the tools again rather than assuming the edit was harmless.\n A successful apply SPENDS the plan: terraform will not run the same plan file twice, so the tool clears it and its records. What follows is a new change set, and step 9 onwards repeat \u2014 plan, price, then apply again. Expect that rather than treating the cleared plan as a failure.\n A deployment with nothing to charge for \u2014 a VPC, subnets, security groups and routes \u2014 still gets a cost record saying so. price_resources reports `nothing_billable`, and that record satisfies the gate: the absence of a charge is an approval, the absence of a quote is not.\n\n## Destroying and resynchronising\n\n- aishell__terraform_destroy applies the teardown aishell__terraform_plan saved. It refuses when\n the state is empty, when the .tf holds plaintext credentials, or when the saved teardown covers\n different targets from the ones this call names.\n \u2605 Call aishell__terraform_plan with `destroy: true` first, passing the SAME `target` list you\n intend to destroy. It returns every resource that would be removed, one entry each \u2014 show that\n list, then call terraform_destroy with the same targets. The saved plan is what destroy runs, so\n the resources that go away are exactly the ones the user saw. Destruction cannot be undone.\n If the deployment also imported existing resources, destroy only what this deployment created: pass their\n addresses as `target: [...]` and leave the imported ones in state. aishell__terraform_state lists\n the addresses; terraform_plan with destroy: true says which ones the deployment would remove.\n- aishell__terraform_refresh \u2014 when the cloud changed outside terraform (edited in the console, a resource deleted by hand), refresh state and then plan to see the difference.\n- aishell__terraform_state \u2014 read state. Without `address` it returns the INVENTORY: one entry per managed resource with its address, type and module. Those addresses are what `terraform_import`, `destroy: true` and `target: [...]` all take. With `address` it returns that one resource in full. The attributes of every resource at once are deliberately not returned \u2014 a real deployment runs to megabytes of them. Both forms also return the security-group rules the state records.\n\n## Hard lines\n\n- Cloud resources are created and destroyed **only** through aishell__terraform_apply and aishell__terraform_destroy. Do not use `POST`/`PUT`/`DELETE` on aishell__openapi_request to create or destroy resources unless the user explicitly asks for the API route and understands the consequences: it skips the cost gate, never enters tfstate, and leaves no trace.\n- Before applying or destroying, name the resources involved and get the user's explicit agreement. Never run these silently.\n- A `.tf` file must never contain a plaintext `access_key`, `secret_key` or `security_token`. The scan runs before init and apply and refuses the run.\n- `cost.json` must exist and its `tf_hash` must match before apply. Editing a `.tf` file invalidates it; recompute the cost.\n- Other `POST`/`DELETE` calls (issuing a voucher, adjusting a quota \u2014 not resource lifecycle) do run, and return a warning. Pass that warning to the user.\n\n## Mainland region filing\n\nIn mainland regions (cn-north-1, cn-north-4, cn-east-3 and others), serving web traffic on ports 80/443 requires ICP filing. Traffic is blocked without it. If the user wants a web port, ask about their filing status first.\n\n## Typical requests\n\n- \"How many ECS instances do I have?\" \u2192 aishell__list_existing_resources with `service: \"ecs\"`\n- \"What did I spend this month?\" \u2192 aishell__openapi_request(\"GET\", <BSS bill API>)\n- \"How many vouchers do I have?\" \u2192 the `balance_summary` field of aishell__list_existing_resources\n- \"What arguments does this resource take?\" \u2192 aishell__provider_schema(deployment, \"huaweicloud_compute_instance\")\n- \"Tear this deployment down\" \u2192 aishell__terraform_destroy, after listing the resources for confirmation\n- \"The cloud changed, resync\" \u2192 aishell__terraform_refresh, then aishell__terraform_plan for the difference\n- \"What is deployed right now?\" \u2192 aishell__terraform_state\n- \"Bring this existing instance under management\" \u2192 write the resource block, then aishell__terraform_import\n\n## Product documentation\n\nFor what a Huawei Cloud product *is* \u2014 features, quotas, limits, charging models \u2014 read the index at https://support.huaweicloud.com/llms.txt. It lists every product's documentation entry point by category; read it to locate the product, then that product's own `llms.txt` for detail.\n\nDo not answer questions about a product's feature boundaries, quotas or charging rules from memory \u2014 they change between releases. For API contracts use aishell__apiexplorer; for what exists in the account use aishell__list_existing_resources; this index is for \"what is this product and what are its limits\".";
49
50
  /**
50
51
  * Register the workflow section.
51
52
  *
@@ -0,0 +1,132 @@
1
+ /**
2
+ * From a terraform resource to what BSS needs to price it.
3
+ *
4
+ * ## The two codes, and why neither is derivable
5
+ *
6
+ * The rating API wants BSS's own vocabulary: a `cloud_service_type`
7
+ * (`hws.service.type.ec2`) and a `resource_type` (`hws.resource.type.vm`).
8
+ * Neither follows from the terraform type by rule:
9
+ *
10
+ * - `huaweicloud_compute_instance` bills under `ec2`, not `compute`;
11
+ * - `huaweicloud_nat_gateway` bills under `natgateway`;
12
+ * - an RDS instance bills under `hws.resource.type.rds.vm`, and
13
+ * `hws.resource.type.rds` is a different product that answers
14
+ * `CBC.6074`, the code that otherwise means "not sold to this account".
15
+ *
16
+ * So the service is carried in a table — one line per service family, with its
17
+ * known irregularities — and the resource type is looked up in the catalogue,
18
+ * choosing among what that service sells by the shape of the resource.
19
+ *
20
+ * ## Why the table is small and the catalogue is asked
21
+ *
22
+ * The provider has 1961 resource types and BSS 2535, and they are not the same
23
+ * set. A table covering both would be wrong within a provider release. The
24
+ * service family is stable — ECS is ECS — so it is written down; the resource
25
+ * type inside a service is data, so it is queried.
26
+ *
27
+ * @module @huaweidevtools/aishell-dsh-deploy/rating-map
28
+ */
29
+ /**
30
+ * How one terraform type becomes a BSS inquiry.
31
+ *
32
+ * `spec` says where the price-bearing value lives, because the provider is
33
+ * inconsistent about it: compute instances take `flavor_id`, managed databases
34
+ * take `flavor`, and a DCS instance additionally needs a `capacity` because one
35
+ * spec code covers every size.
36
+ */
37
+ export interface RatingRule {
38
+ /** The BSS service family, e.g. `hws.service.type.ec2`. */
39
+ readonly serviceType: string;
40
+ /** Attribute names holding the spec, in preference order. */
41
+ readonly specAttributes: readonly string[];
42
+ /**
43
+ * Whether the spec needs an OS suffix. Compute bills Linux and Windows at
44
+ * different rates for one flavour, and the API's own contract says to append
45
+ * `.linux` or `.win`.
46
+ */
47
+ readonly platformSuffix?: boolean;
48
+ /** Whether the resource is sold by capacity, and where that number lives. */
49
+ readonly capacityAttribute?: string;
50
+ /** Where the capacity lives when the provider nests it in a block. */
51
+ readonly capacityBlock?: string;
52
+ /**
53
+ * Which of the service's resource types this shape needs, as a suffix or a
54
+ * full code. Absent means "the service's own code", e.g. `hws.resource.type.dcs`
55
+ * from `hws.service.type.dcs`.
56
+ */
57
+ readonly resourceTypeHint?: string;
58
+ /**
59
+ * Where the attributes live when the provider nests them in a block.
60
+ *
61
+ * An EIP keeps its billing mode in `publicip.type` and its bandwidth in
62
+ * `bandwidth.size`, not at the top level — so a rule that only reads top-level
63
+ * attributes finds nothing and reports the resource as unpriced. The plan
64
+ * carries these as a list of block bodies, one per repetition.
65
+ */
66
+ readonly attributeBlock?: string;
67
+ /**
68
+ * The value substituted into the spec template, when the spec is composed
69
+ * from attributes rather than named by one.
70
+ *
71
+ * An EIP's `resource_spec` is `5_bgp` or `19_bgp`: the leading number is the
72
+ * billing kind and the suffix its charge mode, and only `publicip.type` names
73
+ * it directly. `{value}` is replaced by the attribute named here.
74
+ */
75
+ readonly specAttribute?: string;
76
+ /**
77
+ * The spec code itself, when the provider names none.
78
+ *
79
+ * A load balancer's plan says `l4_flavor_id`, not which BSS product that
80
+ * bills under, and a VPCEP endpoint carries no spec at all — one is sold. For
81
+ * those the catalogue's own code IS the spec, and writing it here is the same
82
+ * kind of decision as `serviceType`: a measured fact, verified by the price
83
+ * that comes back.
84
+ */
85
+ readonly fixedSpec?: string;
86
+ /**
87
+ * Whether the attribute holds the spec in a different case than BSS sells it.
88
+ *
89
+ * APIG's provider attribute is `edition` and takes `Basic`; the billing spec
90
+ * is `BASIC`. The mapping is a case change and nothing else, so it is
91
+ * declared rather than duplicated as a code table that would drift.
92
+ */
93
+ readonly upperCaseSpec?: boolean;
94
+ }
95
+ /**
96
+ * The rating rule for one terraform type.
97
+ *
98
+ * @param type - the terraform resource type.
99
+ * @returns the rule, or `undefined` when this module cannot price that type.
100
+ */
101
+ export declare function ratingRuleFor(type: string): RatingRule | undefined;
102
+ /** The measure unit the API uses for GB. */
103
+ export declare const SIZE_MEASURE_GB = 17;
104
+ /** The usage factor every hourly-priced product bills on. */
105
+ export declare const DURATION_FACTOR = "Duration";
106
+ /** Hours in the month a quote is computed for. */
107
+ export declare const HOURS_PER_MONTH = 730;
108
+ /**
109
+ * The BSS resource type to bill one resource under, from what the service sells.
110
+ *
111
+ * The catalogue answers with several codes per service — `ec2` sells `vm`,
112
+ * `vm.image`, `vm.offline` and more — so the hint picks among them. A service
113
+ * whose own code is the answer (`dcs`) needs no hint: the plain code is one of
114
+ * the entries.
115
+ *
116
+ * @param rule - the resource's rating rule.
117
+ * @param catalogueCodes - every `resource_type` code the service sells.
118
+ * @returns the code, or `undefined` when the catalogue does not carry it.
119
+ */
120
+ export declare function chooseResourceType(rule: RatingRule, catalogueCodes: readonly string[]): string | undefined;
121
+ /**
122
+ * The platform a boot image implies, for the OS suffix.
123
+ *
124
+ * The variant is part of the price, and the API contract states the rule
125
+ * plainly: append `.linux` or `.win` to the flavour id. The platform comes from
126
+ * the image, which the plan names by id.
127
+ *
128
+ * @param imageName - the image's OS description, when the catalogue knows it.
129
+ * @returns the suffix, or `undefined` when the image cannot be classified.
130
+ */
131
+ export declare function platformSuffixOf(imageName: string | undefined): 'linux' | 'windows' | undefined;
132
+ //# sourceMappingURL=rating-map.d.ts.map
@@ -1,12 +1,12 @@
1
1
  /**
2
- * Security-group rule extraction from plan/state JSON (§6.4).
2
+ * Security-group rule extraction from plan or state JSON.
3
3
  *
4
4
  * After terraform_plan / terraform_state, the tool extracts all
5
5
  * secgroup rules from the structured JSON output and surfaces them as a
6
6
  * flat list — pulling rules buried deep in the plan to the top for human
7
7
  * review. No "reasonableness" judgment (that needs AI); just formatting.
8
8
  *
9
- * Provider has two port-field shapes (§6.4 fix):
9
+ * The provider spells ports two ways, and both appear in real plans:
10
10
  * - `ports` (string, e.g. "80,443") — networking_secgroup_rule
11
11
  * - `port_range_min`/`port_range_max` (numbers) — vpc_secgroup_rule
12
12
  * Extraction prefers `ports`, falls back to the range.
@@ -19,25 +19,18 @@ export interface SecgroupRuleView {
19
19
  ports: string;
20
20
  source: string;
21
21
  }
22
- interface PlanResource {
23
- address: string;
24
- type: string;
25
- /** Field values — present in both planned_values (plan) and values (state). */
26
- values?: Record<string, unknown>;
27
- }
28
- interface PlanJson {
29
- planned_values?: {
30
- root_module?: {
31
- resources?: PlanResource[];
32
- };
33
- };
34
- values?: {
35
- root_module?: {
36
- resources?: PlanResource[];
37
- };
38
- };
39
- }
40
- /** Extract secgroup rules from a `terraform show -json` plan or state output. */
41
- export declare function extractSecurityGroups(planOrStateJson: PlanJson): SecgroupRuleView[];
42
- export {};
22
+ /**
23
+ * Extract secgroup rules from a `terraform show -json` plan or state output.
24
+ *
25
+ * The argument is `unknown` because both callers hold a value they have only
26
+ * `JSON.parse`d. Declaring the expected shape instead would force each of them
27
+ * to cast — `as never`, which compiles only because it is assignable to
28
+ * everything, so it disables the check exactly where it matters. Narrowing here
29
+ * keeps that boundary in one place, where the field names are known and a
30
+ * mismatch reads as "no rules" rather than as a crash.
31
+ *
32
+ * @param planOrStateJson - the parsed document, of unverified shape.
33
+ * @returns the rules found, empty when the document does not carry any.
34
+ */
35
+ export declare function extractSecurityGroups(planOrStateJson: unknown): SecgroupRuleView[];
43
36
  //# sourceMappingURL=security-groups.d.ts.map
@@ -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