@huaweidevtools/aishell-dsh-deploy 0.0.17 → 0.0.18

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.
package/lib/index.js CHANGED
@@ -948,11 +948,11 @@ function publicToolName(rawName) {
948
948
  * @param workingDirectory - the host's session-directory service, when mounted.
949
949
  * @returns the definition to hand to `ctx.tools.register`.
950
950
  */
951
- function toToolDefinition(tool, timeoutMs, workingDirectory) {
952
- const name$1 = publicToolName(tool.name);
953
- const description = tool.config.description ?? "";
954
- const parameters = toJsonSchema(tool.config.inputSchema, tool.name);
955
- const validate = argumentValidator(tool.config.inputSchema);
951
+ function toToolDefinition(tool$1, timeoutMs, workingDirectory) {
952
+ const name$1 = publicToolName(tool$1.name);
953
+ const description = tool$1.config.description ?? "";
954
+ const parameters = toJsonSchema(tool$1.config.inputSchema, tool$1.name);
955
+ const validate = argumentValidator(tool$1.config.inputSchema);
956
956
  return {
957
957
  name: name$1,
958
958
  description,
@@ -974,7 +974,7 @@ function toToolDefinition(tool, timeoutMs, workingDirectory) {
974
974
  async execute(args, exec) {
975
975
  const violations = validate(args);
976
976
  if (violations.length > 0) throw new Error(`aishell-deploy: ${name$1}: ${violations.join("; ")}`);
977
- const result = await tool.handler(args, await contextFor(exec, workingDirectory));
977
+ const result = await tool$1.handler(args, await contextFor(exec, workingDirectory));
978
978
  return unwrapOrThrow(result);
979
979
  }
980
980
  };
@@ -1675,9 +1675,13 @@ function withAnchoredPaths(args, ctx) {
1675
1675
  /**
1676
1676
  * The version recorded in a deployment's `.deployment.json`.
1677
1677
  *
1678
- * A deployment snapshot names the code that wrote it, so an old workspace can
1679
- * be traced to the path that produced it. This plugin's version is the honest
1680
- * value: there is no separate build to name.
1678
+ * GENERATED by `scripts/write-deploy-version.mjs` — do not edit. It is
1679
+ * rewritten on every build from the package manifest, so the two cannot
1680
+ * disagree; a hand-written value here would drift from the version that
1681
+ * actually ships, and the field exists to make that traceable.
1682
+ *
1683
+ * A deployment snapshot names the code that wrote it, so an old workspace can be
1684
+ * traced to the release that produced it.
1681
1685
  *
1682
1686
  * @module @huaweidevtools/aishell-dsh-deploy/version
1683
1687
  */
@@ -1688,7 +1692,7 @@ function withAnchoredPaths(args, ctx) {
1688
1692
  * written by earlier releases carry it — so it is kept even though there is no
1689
1693
  * server.
1690
1694
  */
1691
- const SERVER_VERSION = "aishell-deploy 0.1.0";
1695
+ const SERVER_VERSION = "aishell-deploy 0.0.18";
1692
1696
 
1693
1697
  //#endregion
1694
1698
  //#region src/deployment-state.ts
@@ -2365,7 +2369,7 @@ async function runTerraform(cwd, args, extraEnv = []) {
2365
2369
  function registerDeploymentTools(registrar) {
2366
2370
  registrar.registerTool("create_deployment", {
2367
2371
  title: "Create deployment",
2368
- description: "Create or reuse a deployment workspace directory. If the directory does not exist, create it and write .deployment.json (state snapshot). Does NOT create any file inside it. If the directory exists but is not a deployment (non-empty, no .deployment.json), return an error.",
2372
+ description: "Create or reuse a deployment workspace directory. The only file it writes is .deployment.json, the state snapshot the gates later read — no .tf, no plan. If the directory already holds a deployment, it returns that snapshot instead of touching it. If the directory is non-empty and is not a deployment, it refuses rather than writing into someone else's files.",
2369
2373
  annotations: LOCAL_WRITE,
2370
2374
  inputSchema: z.object({ deployment: deploymentParam })
2371
2375
  }, guard(async (args) => handleCreate(args.deployment)));
@@ -3724,7 +3728,7 @@ const COST_FILE$1 = "cost.json";
3724
3728
  function registerPricingTool(registrar) {
3725
3729
  registrar.registerTool("price_resources", {
3726
3730
  title: "Price the resources in the saved plan",
3727
- description: "Read the plan terraform_plan saved and quote each priceable resource against this account's own on-demand prices, then write cost.json. It prices the PLAN, not the .tf: a block with count = 3 is three priced instances, for_each is one per key, and a module's resources are visible — none of which the .tf files show. Each figure is one month (730 hours) of the resource, with the list price it was discounted from and the moment of the inquiry. Compute instances (Linux and Windows bill separately), RDS instances, DCS instances, EVS volumes and EIPs are priced. Anything else — a NAT gateway, a load balancer, an API gateway, a bucket, a resource whose spec came from a variable — is listed as UNPRICED with the reason, never estimated. A total that silently omits them understates the bill, so say which ones they are. Each resource is priced in the region its provider block names, so a deployment spanning several regions gets a price for each — but a region written as a variable cannot be read from the plan, and those resources are reported unpriced rather than priced against a guess. Write the region as a literal in the provider block. Call it AFTER terraform_plan, and before showing the user a cost.",
3731
+ description: "Read the plan terraform_plan saved and quote each priceable resource against this account's own on-demand prices, then write cost.json. It prices the PLAN, not the .tf: a block with count = 3 is three priced instances, for_each is one per key, and a module's resources are visible — none of which the .tf files show. Each figure is one month (730 hours) of the resource, with the list price it was discounted from and the moment of the inquiry. It prices compute instances (Linux and Windows bill separately), RDS, DCS, EVS volumes, EIPs, NAT gateways, ELB load balancers, APIG instances and VPCEP endpoints. Anything else — a bucket, a resource whose spec came from a variable — is listed as UNPRICED with the reason, never estimated. Read that list rather than assuming a type is covered: a total that silently omits the unpriced ones understates the bill, so say which they are. Each resource is priced in the region its provider block names, so a deployment spanning several regions gets a price for each — but a region written as a variable cannot be read from the plan, and those resources are reported unpriced rather than priced against a guess. Write the region as a literal in the provider block. It reads the saved plan, so a deployment that has not been planned has nothing to price.",
3728
3732
  annotations: READ_ONLY_CLOUD,
3729
3733
  inputSchema: z.object({ deployment: deploymentParam })
3730
3734
  }, guard(async (args) => handlePrice(args.deployment)));
@@ -4554,7 +4558,7 @@ async function listImages(project) {
4554
4558
  function registerSpecsTool(registrar) {
4555
4559
  registrar.registerTool("lookup_specs", {
4556
4560
  title: "Look up compute flavours and images, and check a design against them",
4557
- description: "Two uses. WITHOUT `deployment`: list the compute flavours and images this region offers in one availability zone, with each flavour vCPUs, memory and disk, and each image OS, minimum disk and minimum memory. Call this BEFORE writing a .tf that needs `flavor_id` or `image_id` — those are values only the region knows, and inventing them produces a file that passes terraform validate and fails at apply. WITH `deployment`: read the .tf files and check every flavor_id, flavor_name, image_id and image_name they name against the catalogue, reporting any that the region does not offer in that zone, plus images whose minimum disk or memory the chosen flavour cannot meet. terraform validate cannot see any of this: it checks only that the value is a string. The numbers are returned so the user can judge suitability; this tool does not judge it.",
4561
+ description: "Two uses. WITHOUT `deployment`: list the compute flavours and images this region offers in one availability zone, with each flavour vCPUs, memory and disk, and each image OS, minimum disk and minimum memory. `flavor_id` and `image_id` are values only the region knows — an invented one passes terraform validate, which checks only that the value is a string, and fails at apply. WITH `deployment`: read the .tf files and check every flavor_id, flavor_name, image_id and image_name they name against the catalogue, reporting any that the region does not offer in that zone, plus images whose minimum disk or memory the chosen flavour cannot meet. terraform validate cannot see any of this: it checks only that the value is a string. The numbers are returned so the user can judge suitability; this tool does not judge it.",
4558
4562
  annotations: READ_ONLY_CLOUD,
4559
4563
  inputSchema: z.object({
4560
4564
  availability_zone: z.string().describe("The zone to ask about, e.g. \"cn-north-4a\". A flavour exists per zone, so this is required — asking without it would report a flavour as available when only another zone carries it."),
@@ -6231,12 +6235,50 @@ function inventoryToD2(topology) {
6231
6235
  };
6232
6236
  for (const root of topology.roots) write$1(root, 0);
6233
6237
  if (topology.roots.length > 0) lines.push("");
6238
+ for (const edge of drawnEdges(topology)) lines.push(`${nodeId(edge.from)} -> ${nodeId(edge.to)}: ${quote(edge.attribute)} { class: [${CONNECTION_CLASS$1}] }`);
6239
+ return lines.join("\n");
6240
+ }
6241
+ /**
6242
+ * The relationships worth drawing as an arrow.
6243
+ *
6244
+ * Three kinds of association are dropped, each for a reason that shows up on a
6245
+ * real account rather than being a preference:
6246
+ *
6247
+ * 1. **Containment.** A parent/child edge is already said by the nesting, and
6248
+ * an arrow beside it draws the same fact twice — the line leaves the box
6249
+ * it never left.
6250
+ * 2. **The reverse of another edge.** The inventory reports both ends of a
6251
+ * relationship: an EIP names its bandwidth and the bandwidth names the
6252
+ * EIP, a server names its volumes and each volume names the server. Both
6253
+ * are true, but one arrow per pair says as much and does not put two
6254
+ * lines on top of each other. Measured on a live 49-resource account:
6255
+ * 40 associations, 32 distinct pairs.
6256
+ * 3. **A reference that points at an ancestor.** The VPC a resource sits in
6257
+ * is visible from where the resource is drawn; a line from inside the
6258
+ * container out to it adds no fact and crosses the container's border to
6259
+ * say nothing. Five of those on the same account, all of them `vpc_id`.
6260
+ *
6261
+ * What is left is a genuine cross-container reference: a resource here naming
6262
+ * a resource there. Those are the ones a reader has to follow, so they are the
6263
+ * ones that get a line.
6264
+ *
6265
+ * @param topology - the derived picture.
6266
+ * @returns the edges to draw, deduplicated and without the ones nesting implies.
6267
+ */
6268
+ function drawnEdges(topology) {
6234
6269
  const parentOf = new Map(topology.nodes.map((node) => [node.id, node.parent]));
6270
+ const ancestorsOf = new Map(topology.nodes.map((node) => [node.id, node.ancestors]));
6271
+ const seenPairs = new Set();
6272
+ const drawn = [];
6235
6273
  for (const edge of topology.edges) {
6236
6274
  if (parentOf.get(edge.from) === edge.to) continue;
6237
- lines.push(`${nodeId(edge.from)} -> ${nodeId(edge.to)}: ${quote(edge.attribute)} { class: [${CONNECTION_CLASS$1}] }`);
6275
+ if ((ancestorsOf.get(edge.from) ?? []).includes(edge.to)) continue;
6276
+ const pair = [edge.from, edge.to].sort().join("\0");
6277
+ if (seenPairs.has(pair)) continue;
6278
+ seenPairs.add(pair);
6279
+ drawn.push(edge);
6238
6280
  }
6239
- return lines.join("\n");
6281
+ return drawn;
6240
6282
  }
6241
6283
  /**
6242
6284
  * The D2 identifier for a cloud id.
@@ -6559,11 +6601,11 @@ const CONFIG_EXTENSION = ".tf";
6559
6601
  function registerDesignTool(registrar) {
6560
6602
  registrar.registerTool("validate_design", {
6561
6603
  title: "Validate the network design and draw it",
6562
- description: "Check the deployment's Huawei Cloud network design (.tf files: VPC, subnets, security groups, gateways) and render it as a diagram. How the VPCs reach each other is drawn as a labelled edge rather than a box: a peering connection, a VPCEP endpoint and a route are relationships between networks, not devices, so a picture that gave each one its own shape would suggest the network contains something it does not. They are also reported under `connections` — with `unresolved` when the far network is not declared here (a VPCEP service published in another account, usual case), because that end genuinely is not in this design. The diagram shows the network and what it carries — VPCs, subnets, security groups and their rules, gateways, load balancers, compute instances and managed databases. A configuration also declares things that are not part of that picture (alarm rules, log groups, backups, key pairs, parameter templates); those are counted under `omitted`, by type, and not drawn. Say that the diagram is a view of the design rather than a full inventory. If the configuration declares ONLY such resources there is nothing to draw and the call reports that, naming the types it found. A local module is part of the design: resources declared in a directory the configuration calls with `source = \"./...\"` are checked, drawn and hashed just like files in the workspace root. A module terraform DOWNLOADED is not — that is a dependency, read from whatever the registry serves. Module paths are taken from terraform's own record (`.terraform/modules/modules.json`), so a design written in a module is read before the first apply; before `terraform_init` only the workspace root is read. Runs `terraform validate` when the provider is installed — that is the authoritative check on attribute names, required arguments, value formats and references. Then it runs the checks terraform cannot do: subnet CIDRs overlapping, a subnet outside its VPC, a gateway_ip outside its subnet, and security-group rules open to 0.0.0.0/0 on administrative or database ports. Findings are REPORTED, not enforced: a design with findings still gets its diagram. No cloud credentials are needed, and no resource is created. PASS THE RESOURCES THE DESIGN IS BUILT AROUND: call list_existing_resources first and send the relevant ones as `existing`, so the diagram shows what is already deployed alongside what would be created. An existing subnet takes part in the overlap check — a new subnet that collides with one already deployed is reported here and nowhere else, because that range is not in the .tf. Each existing resource that the .tf references (vpc_id = huaweicloud_vpc.prod.id for a VPC you are not creating) needs `address: \"huaweicloud_vpc.prod\"`; without it the reference cannot be resolved. Use it after writing the network .tf and before adding compute resources. Report the findings and the diagram path to the user and get their agreement before going further.",
6604
+ description: "Check the network design this deployment declares (.tf: VPCs, subnets, security groups and rules, gateways, load balancers, compute and managed databases) and draw it. It runs `terraform validate` when the provider is installed — the authoritative check on attribute names, required arguments and references — then the checks terraform cannot do: subnet CIDRs overlapping, a subnet outside its VPC, a gateway_ip outside its subnet, and security-group rules open to 0.0.0.0/0 on administrative or database ports. Findings are REPORTED, not enforced: a design with findings still gets its diagram. Writes topology.svg and topology.d2 into the deployment and returns their absolute paths. No cloud credentials are needed and no resource is created. The drawing is a VIEW, not an inventory. Resources outside a network picture — alarm rules, log groups, backups, key pairs, parameter templates — come back counted under `omitted` by type and are not drawn; a configuration declaring only those gets a refusal naming them rather than an empty picture. Connections between VPCs (a peering, a VPCEP endpoint, a route) are labelled EDGES rather than boxes, listed under `connections` with `unresolved` when the far network is not declared here. A local module (`source = \"./...\"`) is part of the design and is read, drawn and hashed like the workspace files. A downloaded module is not — it is a dependency. Module paths come from terraform's own record, so a design written inside one is read after `terraform_init` and not before. With `existing` and no .tf at all it draws the account as it stands instead, and reports validation as skipped. See the `existing` parameter for what those have to carry.",
6563
6605
  annotations: READ_ONLY_LOCAL,
6564
6606
  inputSchema: z.object({
6565
6607
  deployment: deploymentParam,
6566
- existing: z.array(ExistingResourceSchema).optional().describe("Cloud resources that already exist and that this design reuses or works around, as reported by list_existing_resources. Pass only the ones the design is about — the whole account is usually the wrong picture. PASS type AND provider EXACTLY AS THE INVENTORY REPORTED THEM. RMS names resources in its own vocabulary (\"vpcs\", \"securityGroups\", \"instances\"), which is not the terraform type; translating it by hand produces names that do not exist (\"huaweicloud_security_group\" for \"securityGroups\"). The pair is also what disambiguates: \"instances\" under rds is a database, under apig it is not. PASS `properties` TOO, copied verbatim. With no .tf, `properties` is the only input this tool has: the nesting and the connections are derived from ids appearing in it, so a resource without one is drawn as an isolated box and the relationships it has are lost. Each needs id and type; parent (the containing resource's cloud ID), name, cidr and flavor make the box readable. They are drawn dashed to mark them as already present. Passing `existing` with no .tf at all is legitimate: it draws the account as it stands, and validation reports itself as skipped.")
6608
+ existing: z.array(ExistingResourceSchema).optional().describe("Cloud resources that already exist and that this design reuses or works around, as reported by list_existing_resources. Pass only the ones the design is about — the whole account is usually the wrong picture. Copy `id`, `type`, `provider`, `properties` and `name` verbatim from the inventory; do not translate its vocabulary into terraform type names, which produces names that do not exist. `properties` is what carries the relationships — with no .tf it is this tool's only input, and a resource without one is drawn as an isolated box. An existing resource the .tf references without declaring it (a subnet cut from a VPC that already exists) also needs `address`, the terraform address the reference resolves to. Passing `existing` with no .tf at all draws the account as it stands, and validation reports itself as skipped.")
6567
6609
  })
6568
6610
  }, guard(async (args) => handleValidateDesign(args.deployment, args.existing ?? [])));
6569
6611
  }
@@ -6892,7 +6934,7 @@ function registerOpenApiTools(registrar) {
6892
6934
  }, guard(async (args) => handleApiExplorer(args.productshort, args.api_name, args.compact, args.regions, args.endpoints, args.limit, args.offset)));
6893
6935
  registrar.registerTool("openapi_request", {
6894
6936
  title: "Call HuaweiCloud API",
6895
- description: "Send a signed HTTP request to a HuaweiCloud API endpoint. Credentials are read from secure storage and used to sign the request — AK/SK are never exposed in arguments. GET requests are safe; POST/PUT/DELETE execute but the response includes a warning to inform the user of consequences.",
6937
+ description: "Send a signed HTTP request to a HuaweiCloud API endpoint. Credentials are read from secure storage and used to sign the request — AK/SK are never exposed in arguments. This is the route for READING a service the other tools do not cover; creating or destroying resources belongs to terraform_apply and terraform_destroy, which carry the cost and design gates this call skips. GET is safe. POST/PUT/DELETE execute, and the response carries a warning naming the consequence — pass that warning to the user. Pass `fields` with JSONPath expressions rather than reading a large body into the conversation: one ECS list can be hundreds of KB, and the few values you need come back as {path, value} pairs. Both plain dot paths and full JSONPath work. A body over 4 MB is truncated and says so.",
6896
6938
  annotations: CLOUD_MUTABLE_API,
6897
6939
  inputSchema: z.object({
6898
6940
  method: z.enum([
@@ -7600,7 +7642,7 @@ function asInventorySubnet(subnet, region) {
7600
7642
  function registerExistingResourcesTool(registrar) {
7601
7643
  registrar.registerTool("list_existing_resources", {
7602
7644
  title: "List existing cloud resources",
7603
- description: "List HuaweiCloud resources the user already owns (for reuse in a deployment) via RMS (Resource Management Service). Two stages: by default returns a SUMMARY (provider→type→region→count, cheap, cross-region) so you see what exists before drilling in. Pass service, region, or detail=true to get the full resource list (id/name/properties — use after the summary to narrow down). Detail mode is paginated: if the response has next_marker, pass it back as marker to fetch the next page. Also returns balance_summary (balances + coupons). Call it BEFORE writing the .tf: what the account already has decides what the design reuses and what it must not collide with, and nothing in the configuration can tell you that. Reuse eligibility is a judgment call, not decided here. NOTE: RMS data may lag — resources recently created or destroyed may not reflect immediately. When timing matters (e.g. verifying cleanup after destroy), be aware this data source is not real-time.",
7645
+ description: "List HuaweiCloud resources the user already owns (for reuse in a deployment) via RMS (Resource Management Service). Two stages: by default returns a SUMMARY (provider→type→region→count, cheap, cross-region) so you see what exists before drilling in. Pass service, region, or detail=true to get the full resource list (id/name/properties — use after the summary to narrow down). Detail mode is paginated: if the response has next_marker, pass it back as marker to fetch the next page. Also returns balance_summary (balances + coupons). What the account already has decides what a design can reuse and what it must not collide with, and nothing in a configuration can tell you that. Reuse eligibility is a judgment call, not decided here. NOTE: RMS data may lag — resources recently created or destroyed may not reflect immediately. When timing matters (e.g. verifying cleanup after destroy), be aware this data source is not real-time.",
7604
7646
  annotations: READ_ONLY_CLOUD,
7605
7647
  inputSchema: z.object({
7606
7648
  service: z.string().optional().describe("Filter by RMS provider in detail mode: \"vpc\"|\"ecs\"|\"rds\"|\"elb\"|..."),
@@ -7796,7 +7838,7 @@ async function listSubnets(regions) {
7796
7838
  function registerProviderSchemaTool(registrar) {
7797
7839
  registrar.registerTool("provider_schema", {
7798
7840
  title: "Extract provider schema",
7799
- description: "Extract the schema of the locally installed huaweicloud terraform provider by running `terraform providers schema -json` in the deployment directory. Without resource_type: return the list of all resource and data-source type names (the full schema is ~6MB, too large to return whole). Use the `filter` arg to narrow by substring (e.g. filter=\"vpc\" returns huaweicloud_vpc, huaweicloud_vpc_route, ...). With resource_type: return that type's full schema (attributes, types, required-ness, nested blocks). Call AFTER terraform_init.",
7841
+ description: "Extract the schema of the locally installed huaweicloud terraform provider by running `terraform providers schema -json` in the deployment directory. Without resource_type: return the list of all resource and data-source type names (the full schema is ~6MB, too large to return whole). Use the `filter` arg to narrow by substring (e.g. filter=\"vpc\" returns huaweicloud_vpc, huaweicloud_vpc_route, ...). With resource_type: return that type's full schema (attributes, types, required-ness, nested blocks). The schema is read from what terraform installed, so a provider that is not installed yet answers nothing — call terraform_init first.",
7800
7842
  annotations: READ_ONLY_LOCAL,
7801
7843
  inputSchema: z.object({
7802
7844
  deployment: deploymentParam,
@@ -8447,7 +8489,7 @@ async function handleInstall(terraformPath, binaryMirrors, extraEnv = []) {
8447
8489
  function registerInit(registrar) {
8448
8490
  registrar.registerTool("terraform_init", {
8449
8491
  title: "Terraform init",
8450
- description: "Run `terraform init`. Generates <deployment>/.terraformrc with provider mirror config (if not user-provided), sets TF_PLUGIN_CACHE_DIR, pulls provider plugins. Credential env injected from keychain.",
8492
+ description: "Run `terraform init` to install the provider plugins. It writes <deployment>/.terraformrc with the provider mirror configuration unless one is already there or `provider_mirrors` is empty, points TF_PLUGIN_CACHE_DIR at the shared provider cache when that directory is writable, and injects the stored credentials into the subprocess environment so the provider can authenticate.",
8451
8493
  annotations: CLOUD_WRITE,
8452
8494
  inputSchema: z.object({
8453
8495
  deployment: deploymentParam,
@@ -8485,11 +8527,11 @@ async function handleInit(deployment, providerMirrors, extraEnv = []) {
8485
8527
  function registerPlan(registrar) {
8486
8528
  registrar.registerTool("terraform_plan", {
8487
8529
  title: "Terraform plan",
8488
- description: "Run `terraform plan` and save it to plan.tfplan. Returns the CHANGES, not the raw plan document: one entry per resource with its action (create / update / replace / destroy), the attribute names an update touches, and what forces a replacement. Also returns the security-group rules the change would create, so they can be reviewed without opening the plan. terraform_apply runs this saved plan, and records the configuration it was computed from — so any .tf edit after planning requires another call to this tool. With destroy: true it previews the DESTRUCTION instead: the same change list, every entry delete, written to a separate file so the apply plan is untouched. Pass the same `target` list you intend to destroy — terraform_destroy applies THIS saved plan, so the resources that go away are exactly the ones shown here. Show that list before calling terraform_destroy.",
8530
+ description: "Run `terraform plan` and save it to plan.tfplan. Returns the CHANGES, not the raw plan document: one entry per resource with its action (create / update / replace / destroy), the attribute names an update touches, and what forces a replacement. Also returns the security-group rules the change would create, so they can be reviewed without opening the plan. terraform_apply runs this saved plan, and records the configuration it was computed from — so any .tf edit after planning requires another call to this tool. With destroy: true it previews the DESTRUCTION instead: the same change list, every entry delete, written to a separate file so the apply plan is untouched. The `target` list given here is baked into the saved teardown — terraform_destroy applies THIS saved plan and refuses a target list that differs from it.",
8489
8531
  annotations: READ_ONLY_CLOUD,
8490
8532
  inputSchema: z.object({
8491
8533
  deployment: deploymentParam,
8492
- destroy: z.boolean().optional().describe("Preview what terraform_destroy would remove instead of what an apply would change. Use this to show the user the destruction list before calling terraform_destroy: the plan names every resource that goes away, so they can approve it and choose the target subset. Writes a separate destroy.plan.tfplan and does not touch the apply plan."),
8534
+ destroy: z.boolean().optional().describe("Preview what terraform_destroy would remove instead of what an apply would change. The plan names every resource that goes away, and terraform_destroy later applies this same saved plan. Writes a separate destroy.plan.tfplan and does not touch the apply plan."),
8493
8535
  target: z.array(z.string()).optional().describe("With destroy: true only — the resource addresses to preview removing, e.g. [\"huaweicloud_vpc.main\"]. Omit to preview removing everything the deployment manages. terraform_destroy must be given the same list."),
8494
8536
  env: envParam
8495
8537
  })
@@ -8642,11 +8684,11 @@ function registerDestroy(registrar) {
8642
8684
  "terraform_destroy",
8643
8685
  {
8644
8686
  title: "Terraform destroy",
8645
- description: "Run `terraform apply` on the destruction `terraform_plan({ destroy: true })` saved. Permanently deletes cloud resources managed by this deployment — irreversible. MUST confirm with the user before calling. Safety gates: refuses if the state is empty (nothing to destroy), if .tf files contain plaintext credentials (same scan as init/apply), or if no teardown was previewed for exactly these targets — a destroy computes its own plan otherwise, which need not be the list the user approved. By default destroys ALL resources in the deployment. Pass `target` to destroy only specific resources by address — use this to spare imported (reuse) resources: destroy only the newly-created resources, leaving imported ones in state. Call terraform_state first to list resource addresses. The targets must match the ones passed to terraform_plan with destroy: true.",
8687
+ description: "Run `terraform apply` on the destruction `terraform_plan({ destroy: true })` saved. Permanently deletes cloud resources managed by this deployment — irreversible. Refuses to run without a saved teardown covering exactly these targets: a destroy that computed its own plan would remove a set of resources nobody previewed. Also refuses when the state is empty (nothing to destroy) or when the .tf files hold plaintext credentials (the same scan init and apply run). By default destroys ALL resources in the deployment. Pass `target` to destroy only specific resources by address — use this to spare imported (reuse) resources: destroy only the newly-created resources, leaving imported ones in state. `target` must match the list terraform_plan was given with destroy: true, or the gate refuses: the saved teardown is the approval record, and a different target list is a different destruction than the one previewed.",
8646
8688
  annotations: CLOUD_DESTRUCTIVE,
8647
8689
  inputSchema: z.object({
8648
8690
  deployment: deploymentParam,
8649
- target: z.array(z.string()).optional().describe("Resource addresses to destroy selectively. e.g. [\"huaweicloud_vpc.main\", \"huaweicloud_vpc_subnet.sub1\"]. Omit to destroy ALL resources (default). Use terraform_state to list addresses. Use this to spare imported resources: destroy only newly-created resources, leaving imported ones in state."),
8691
+ target: z.array(z.string()).optional().describe("Resource addresses to destroy selectively. e.g. [\"huaweicloud_vpc.main\", \"huaweicloud_vpc_subnet.sub1\"]. Omit to destroy ALL resources (default). Must equal the target list given to terraform_plan with destroy: true. Use this to spare imported resources: destroy only newly-created resources, leaving imported ones in state."),
8650
8692
  env: envParam
8651
8693
  })
8652
8694
  },
@@ -8692,7 +8734,7 @@ function registerDestroy(registrar) {
8692
8734
  function registerRefresh(registrar) {
8693
8735
  registrar.registerTool("terraform_refresh", {
8694
8736
  title: "Terraform refresh",
8695
- description: "Run `terraform apply -refresh-only`. Updates tfstate to reflect real cloud state.",
8737
+ description: "Reconcile tfstate with the cloud: runs `terraform apply -refresh-only`, which records what each managed resource looks like now without changing any of them. Use it when something changed outside terraform — edited in the console, deleted by hand — then call terraform_plan to see the difference.",
8696
8738
  annotations: READ_ONLY_CLOUD,
8697
8739
  inputSchema: z.object({
8698
8740
  deployment: deploymentParam,
@@ -8835,7 +8877,7 @@ function stateInventory(stateJson) {
8835
8877
  function registerImport(registrar) {
8836
8878
  registrar.registerTool("terraform_import", {
8837
8879
  title: "Terraform import",
8838
- description: "Run `terraform import` to bring an existing cloud resource into tfstate without creating it. Use after list_existing_resources to reuse an existing resource: write the resource block in .tf (with the same address), then import to populate its state. The resource address and ID format depend on the provider type — check provider docs or apiexplorer for the import syntax (e.g. huaweicloud_compute_instance.myvm <instance-id>). IMPORT DOES NOT RECONCILE. It records what the CLOUD holds; the block you wrote may say something else, and nothing compares them here. Run terraform_plan immediately afterwards: a diff means the block does not match the real resource, and applying it would CHANGE a resource the user asked you to leave alone — possibly by replacing it. Show that diff before going on.",
8880
+ description: "Run `terraform import` to bring an existing cloud resource into tfstate without creating it. The resource address and ID format depend on the provider type — check provider docs or apiexplorer for the import syntax (e.g. huaweicloud_compute_instance.myvm <instance-id>). IMPORT DOES NOT RECONCILE. It records what the CLOUD holds; the resource block in the .tf may say something else, and nothing compares them here. A plan run afterwards shows that difference as a diff — applying it would CHANGE a resource that was meant to be left alone, possibly by replacing it.",
8839
8881
  annotations: READ_ONLY_CLOUD,
8840
8882
  inputSchema: z.object({
8841
8883
  deployment: deploymentParam,
@@ -9279,98 +9321,269 @@ function registerPermissionPolicyContext(ctx, current$1) {
9279
9321
  /** Name this contribution registers under; unique across the assembled prompt. */
9280
9322
  const WORKFLOW_SECTION_NAME = "aishell:deploy-workflow";
9281
9323
  /**
9282
- * What the model reads.
9324
+ * A tool name as the model sees it.
9283
9325
  *
9284
- * Written in English like every other host-side string in this repo — prompt
9285
- * sections are host text, and the browser half owns localized copy. The model
9286
- * relays the answer in the user's language; the instructions do not need to
9287
- * change language to do that.
9326
+ * @param name - the tool's own name.
9327
+ * @returns the registered name.
9328
+ */
9329
+ function tool(name$1) {
9330
+ return `aishell__${name$1}`;
9331
+ }
9332
+ /**
9333
+ * The opening paragraph, which needs no particular tool.
9288
9334
  *
9289
- * Every tool name appears as the model sees it, `aishell__<name>`, so a model
9290
- * can copy it straight into a call.
9335
+ * It names the reason to prefer these tools over shell: the gates. That is true
9336
+ * as long as any of them exists.
9291
9337
  */
9292
- 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.
9293
-
9294
- ## Deployment flow
9295
-
9296
- Steps marked ★ require the user's explicit agreement before you continue.
9297
-
9298
- 1. aishell__auth — 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.
9299
- 2. aishell__list_existing_resources — 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.
9300
- aishell__create_deployment — create or reuse the deployment workspace.
9301
- 3. aishell__terraform_install — 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 — call it before \`terraform_init\`, not after it fails with "terraform not found".
9302
- aishell__terraform_init — 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" — a design nobody checked against the provider schema. The gate here also scans for plaintext credentials and refuses if it finds any.
9303
- aishell__apiexplorer — 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).
9304
- aishell__terraform_examples_export — write \`.tf\` examples to a directory. That directory is a reference target, not the deployment workspace.
9305
- 4. 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 — the network design is what decides those, not the other way round — so it needs no cloud credentials either.
9338
+ const PREAMBLE = `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.`;
9339
+ /**
9340
+ * The deployment flow, in the order a deployment is built.
9341
+ *
9342
+ * Each step names the tools it is about. A step whose tools are absent is
9343
+ * dropped and the rest renumber, which is why the text carries `%n` rather than
9344
+ * a number.
9345
+ */
9346
+ const FLOW = [
9347
+ {
9348
+ requires: ["auth"],
9349
+ text: `%n. ${tool("auth")} — 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.`
9350
+ },
9351
+ {
9352
+ requires: ["list_existing_resources"],
9353
+ text: `%n. ${tool("list_existing_resources")} — 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. On \`service: "vpc"\` the answer also carries the SUBNETS, read from the VPC API because RMS does not report them — pass those on like any other resource.`
9354
+ },
9355
+ {
9356
+ requires: ["create_deployment", "validate_design"],
9357
+ text: ` ${tool("create_deployment")} — create or reuse the deployment workspace. If the user only wants to SEE what is deployed, skip this and pass the inventory straight to ${tool("validate_design")}, which draws the account as it stands.`
9358
+ },
9359
+ {
9360
+ requires: ["terraform_install"],
9361
+ text: `%n. ${tool("terraform_install")} — 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 — call it before \`terraform_init\`, not after it fails with "terraform not found".`
9362
+ },
9363
+ {
9364
+ requires: ["terraform_init", "validate_design"],
9365
+ text: ` ${tool("terraform_init")} — 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" — a design nobody checked against the provider schema. The gate here also scans for plaintext credentials and refuses if it finds any.`
9366
+ },
9367
+ {
9368
+ requires: ["apiexplorer"],
9369
+ text: ` ${tool("apiexplorer")} — 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).`
9370
+ },
9371
+ {
9372
+ requires: ["terraform_examples_export"],
9373
+ text: ` ${tool("terraform_examples_export")} — write \`.tf\` examples to a directory. That directory is a reference target, not the deployment workspace.`
9374
+ },
9375
+ {
9376
+ requires: ["validate_design"],
9377
+ text: `%n. 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 — the network design is what decides those, not the other way round — so it needs no cloud credentials either.
9306
9378
  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.
9307
- aishell__validate_design — 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.
9379
+ ${tool("validate_design")} — 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.
9308
9380
  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 — 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.
9309
- 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.
9381
+ Pass the resources from the inventory 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.
9310
9382
  ★ 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.
9311
- ★ 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.
9312
- 5. Report the balance summary from the step-2 inventory: balance and vouchers.
9313
- 6. Decide per component: reuse or create.
9314
- - 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.
9315
- ★ An import does NOT check that the block you wrote matches the resource that exists — 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.
9316
- - 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.
9317
- Pick a flavour and an image whose minimum disk and memory the flavour can meet, and state the choice to the user — this is the decision the price hangs on.
9318
- 7. 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.
9319
- 8. aishell__provider_schema — the argument contract for a resource type, when you need it.
9320
- 9. aishell__terraform_plan — 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 — for a replace — what forces the rebuild. It also returns the security-group rules the change would create.
9321
- ★ 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" — name them. Do not describe the plan as reversible.
9322
- 10. aishell__price_resources — 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 — none of which the .tf files show. Each figure is a month (730 hours), with the list price and the moment of the inquiry.
9323
- 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 — a total that silently omits them understates the bill.
9324
- 11. ★ 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.
9325
- 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.
9326
- 12. aishell__terraform_apply — 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 — 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 — call the tools again rather than assuming the edit was harmless.
9327
- 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 — plan, price, then apply again. Expect that rather than treating the cleared plan as a failure.
9328
- A deployment with nothing to charge for — a VPC, subnets, security groups and routes — 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.
9329
-
9330
- ## Destroying and resynchronising
9331
-
9332
- - aishell__terraform_destroy applies the teardown aishell__terraform_plan saved. It refuses when
9333
- the state is empty, when the .tf holds plaintext credentials, or when the saved teardown covers
9334
- different targets from the ones this call names.
9335
- ★ Call aishell__terraform_plan with \`destroy: true\` first, passing the SAME \`target\` list you
9336
- intend to destroy. It returns every resource that would be removed, one entry each — show that
9337
- list, then call terraform_destroy with the same targets. The saved plan is what destroy runs, so
9338
- the resources that go away are exactly the ones the user saw. Destruction cannot be undone.
9339
- If the deployment also imported existing resources, destroy only what this deployment created: pass their
9340
- addresses as \`target: [...]\` and leave the imported ones in state. aishell__terraform_state lists
9341
- the addresses; terraform_plan with destroy: true says which ones the deployment would remove.
9342
- - aishell__terraform_refresh — when the cloud changed outside terraform (edited in the console, a resource deleted by hand), refresh state and then plan to see the difference.
9343
- - aishell__terraform_state — 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 — a real deployment runs to megabytes of them. Both forms also return the security-group rules the state records.
9344
-
9345
- ## Hard lines
9383
+ ★ 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.`
9384
+ },
9385
+ {
9386
+ requires: ["list_existing_resources"],
9387
+ text: `%n. Report the balance summary from the inventory: balance and vouchers.`
9388
+ },
9389
+ {
9390
+ requires: [
9391
+ "terraform_import",
9392
+ "terraform_plan",
9393
+ "lookup_specs"
9394
+ ],
9395
+ text: `%n. Decide per component: reuse or create.
9396
+ - Reuse: the spec and charging are fixed by the existing resource. Write the resource block, then ${tool("terraform_import")} to bring it into state. This needs the provider installed.
9397
+ ★ An import does NOT check that the block you wrote matches the resource that exists — it records what the cloud holds. Call ${tool("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.
9398
+ - Create: ${tool("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.
9399
+ Pick a flavour and an image whose minimum disk and memory the flavour can meet, and state the choice to the user — this is the decision the price hangs on.`
9400
+ },
9401
+ {
9402
+ requires: ["terraform_plan"],
9403
+ text: `%n. Add the compute, database and other resources to the same \`.tf\` files, from the design agreed above and the flavours chosen. Credentials come from the environment; never write \`access_key\`, \`secret_key\` or \`security_token\` into a \`.tf\` file.
9404
+ ${tool("provider_schema")} — the argument contract for a resource type, when you need it.
9405
+ ${tool("terraform_plan")} — 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 — for a replace — what forces the rebuild. It also returns the security-group rules the change would create.
9406
+ ★ 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" — name them. Do not describe the plan as reversible.`
9407
+ },
9408
+ {
9409
+ requires: ["price_resources", "terraform_plan"],
9410
+ text: `%n. ${tool("price_resources")} — 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 — none of which the .tf files show. Each figure is a month (730 hours), with the list price and the moment of the inquiry.
9411
+ It prices compute instances (Linux and Windows bill separately, from the image), RDS, DCS, EVS volumes, EIPs, NAT gateways, ELB load balancers, APIG instances and VPCEP endpoints. 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. Read that list rather than assuming a type is covered. Say which ones are unpriced — a total that silently omits them understates the bill.`
9412
+ },
9413
+ {
9414
+ requires: ["price_resources"],
9415
+ text: `%n. ★ 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. Get the user's explicit agreement on the specification and the cost.
9416
+ 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.`
9417
+ },
9418
+ {
9419
+ requires: ["terraform_apply"],
9420
+ text: `%n. ${tool("terraform_apply")} — run it. Five gates run first: the design was checked by ${tool("validate_design")}, the cost was quoted by ${tool("price_resources")}, and ${tool("terraform_plan")} computed the saved plan — 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 the plan.
9421
+ 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 — plan, price, then apply again. Expect that rather than treating the cleared plan as a failure.
9422
+ A deployment with nothing to charge for — a VPC, subnets, security groups and routes — 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.`
9423
+ }
9424
+ ];
9425
+ /**
9426
+ * Destroying and resynchronising.
9427
+ *
9428
+ * Its own block because it is a different task, reached from a different place
9429
+ * in a conversation, and because each bullet is about a different tool.
9430
+ */
9431
+ const DESTROYING = [
9432
+ {
9433
+ requires: [
9434
+ "terraform_destroy",
9435
+ "terraform_plan",
9436
+ "terraform_state"
9437
+ ],
9438
+ text: `- ${tool("terraform_destroy")} applies the teardown ${tool("terraform_plan")} saved. It refuses when the state is empty, when the .tf holds plaintext credentials, or when the saved teardown covers different targets from the ones this call names.
9439
+ ★ Call ${tool("terraform_plan")} with \`destroy: true\` first, passing the SAME \`target\` list you intend to destroy. It returns every resource that would be removed, one entry each — show that list, then call terraform_destroy with the same targets. The saved plan is what destroy runs, so the resources that go away are exactly the ones the user saw. Destruction cannot be undone.
9440
+ If the deployment also imported existing resources, destroy only what this deployment created: pass their addresses as \`target: [...]\` and leave the imported ones in state. ${tool("terraform_state")} lists the addresses; terraform_plan with destroy: true says which ones the deployment would remove.`
9441
+ },
9442
+ {
9443
+ requires: ["terraform_refresh", "terraform_plan"],
9444
+ text: `- ${tool("terraform_refresh")} — when the cloud changed outside terraform (edited in the console, a resource deleted by hand), refresh state and then plan to see the difference.`
9445
+ },
9446
+ {
9447
+ requires: ["terraform_state"],
9448
+ text: `- ${tool("terraform_state")} — 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 — a real deployment runs to megabytes of them. Both forms also return the security-group rules the state records.`
9449
+ }
9450
+ ];
9451
+ /** The rules that hold whenever the tools are present at all. */
9452
+ const HARD_LINES = `## Hard lines
9346
9453
 
9347
9454
  - 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.
9348
9455
  - Before applying or destroying, name the resources involved and get the user's explicit agreement. Never run these silently.
9349
9456
  - 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.
9350
9457
  - \`cost.json\` must exist and its \`tf_hash\` must match before apply. Editing a \`.tf\` file invalidates it; recompute the cost.
9351
- - Other \`POST\`/\`DELETE\` calls (issuing a voucher, adjusting a quota — not resource lifecycle) do run, and return a warning. Pass that warning to the user.
9352
-
9353
- ## Mainland region filing
9354
-
9355
- In 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.
9458
+ - Other \`POST\`/\`DELETE\` calls (issuing a voucher, adjusting a quota — not resource lifecycle) do run, and return a warning. Pass that warning to the user.`;
9459
+ /** Region advice that is independent of which tools are present. */
9460
+ const REGION_FILING = `## Mainland region filing
9356
9461
 
9357
- ## Typical requests
9358
-
9359
- - "How many ECS instances do I have?" → aishell__list_existing_resources with \`service: "ecs"\`
9360
- - "What did I spend this month?" → aishell__openapi_request("GET", <BSS bill API>)
9361
- - "How many vouchers do I have?" → the \`balance_summary\` field of aishell__list_existing_resources
9362
- - "What arguments does this resource take?" → aishell__provider_schema(deployment, "huaweicloud_compute_instance")
9363
- - "Tear this deployment down" → aishell__terraform_destroy, after listing the resources for confirmation
9364
- - "The cloud changed, resync" → aishell__terraform_refresh, then aishell__terraform_plan for the difference
9365
- - "What is deployed right now?" → aishell__terraform_state
9366
- - "Bring this existing instance under management" → write the resource block, then aishell__terraform_import
9367
-
9368
- ## Product documentation
9462
+ In 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.`;
9463
+ /** Answers to the questions that map onto one call each. */
9464
+ const TYPICAL_REQUESTS = [
9465
+ {
9466
+ requires: ["list_existing_resources"],
9467
+ text: `- "How many ECS instances do I have?" → aishell__list_existing_resources with \`service: "ecs"\``
9468
+ },
9469
+ {
9470
+ requires: ["openapi_request"],
9471
+ text: `- "What did I spend this month?" → aishell__openapi_request("GET", <BSS bill API>)`
9472
+ },
9473
+ {
9474
+ requires: ["list_existing_resources"],
9475
+ text: `- "How many vouchers do I have?" → the \`balance_summary\` field of aishell__list_existing_resources`
9476
+ },
9477
+ {
9478
+ requires: ["provider_schema"],
9479
+ text: `- "What arguments does this resource take?" → aishell__provider_schema(deployment, "huaweicloud_compute_instance")`
9480
+ },
9481
+ {
9482
+ requires: ["terraform_destroy"],
9483
+ text: `- "Tear this deployment down" → aishell__terraform_destroy, after listing the resources for confirmation`
9484
+ },
9485
+ {
9486
+ requires: ["terraform_refresh", "terraform_plan"],
9487
+ text: `- "The cloud changed, resync" → aishell__terraform_refresh, then aishell__terraform_plan for the difference`
9488
+ },
9489
+ {
9490
+ requires: ["terraform_state"],
9491
+ text: `- "What is deployed right now?" → aishell__terraform_state`
9492
+ },
9493
+ {
9494
+ requires: ["terraform_import"],
9495
+ text: `- "Bring this existing instance under management" → write the resource block, then aishell__terraform_import`
9496
+ }
9497
+ ];
9498
+ /** Where to read about a product, and what not to answer from memory. */
9499
+ const PRODUCT_DOCS = `## Product documentation
9369
9500
 
9370
9501
  For what a Huawei Cloud product *is* — features, quotas, limits, charging models — 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.
9371
9502
 
9372
9503
  Do not answer questions about a product's feature boundaries, quotas or charging rules from memory — 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".`;
9373
9504
  /**
9505
+ * Whether every tool a block names is registered for this render.
9506
+ *
9507
+ * @param requires - the tool names, without the `aishell__` prefix.
9508
+ * @param present - the lookup bound to the current render scope.
9509
+ * @returns whether the block applies.
9510
+ */
9511
+ function allPresent(requires, present) {
9512
+ return requires.every((name$1) => present(tool(name$1)));
9513
+ }
9514
+ /**
9515
+ * Render an ordered list of steps, numbering only the ones that apply.
9516
+ *
9517
+ * A step whose text begins with indentation is a continuation of the step
9518
+ * before it, and keeps that step's alignment rather than taking a number — the
9519
+ * distinction is carried by the text, because `requires` differs between a
9520
+ * parent step and its continuation.
9521
+ *
9522
+ * @param steps - the steps to consider.
9523
+ * @param present - the lookup bound to the current render scope.
9524
+ * @returns the rendered lines.
9525
+ */
9526
+ function renderSteps(steps, present) {
9527
+ const lines = [];
9528
+ let number = 0;
9529
+ for (const step of steps) {
9530
+ if (!allPresent(step.requires, present)) continue;
9531
+ if (step.text.startsWith(" ")) {
9532
+ lines.push(step.text);
9533
+ continue;
9534
+ }
9535
+ number += 1;
9536
+ lines.push(step.text.replace("%n", String(number)));
9537
+ }
9538
+ return lines;
9539
+ }
9540
+ /**
9541
+ * The workflow text for one render scope.
9542
+ *
9543
+ * @param present - whether a tool with the given name is registered here.
9544
+ * @returns the section's text, empty when nothing it describes is available.
9545
+ */
9546
+ function buildDeployWorkflow(present) {
9547
+ const flow = renderSteps(FLOW, present);
9548
+ const destroying = renderSteps(DESTROYING, present);
9549
+ const typical = renderSteps(TYPICAL_REQUESTS, present);
9550
+ const lifecyclePresent = allPresent(["terraform_apply"], present) || allPresent(["terraform_destroy"], present);
9551
+ const docsPresent = allPresent(["apiexplorer"], present) || allPresent(["list_existing_resources"], present);
9552
+ if (flow.length === 0 && destroying.length === 0 && typical.length === 0 && !lifecyclePresent && !docsPresent) return "";
9553
+ const blocks = [PREAMBLE];
9554
+ if (flow.length > 0) blocks.push([
9555
+ "## Deployment flow",
9556
+ "",
9557
+ "Steps marked ★ require the user's explicit agreement before you continue.",
9558
+ "",
9559
+ ...flow
9560
+ ].join("\n"));
9561
+ if (destroying.length > 0) blocks.push([
9562
+ "## Destroying and resynchronising",
9563
+ "",
9564
+ ...destroying
9565
+ ].join("\n"));
9566
+ if (lifecyclePresent) blocks.push(HARD_LINES);
9567
+ blocks.push(REGION_FILING);
9568
+ if (typical.length > 0) blocks.push([
9569
+ "## Typical requests",
9570
+ "",
9571
+ ...typical
9572
+ ].join("\n"));
9573
+ if (docsPresent) blocks.push(PRODUCT_DOCS);
9574
+ return blocks.join("\n\n");
9575
+ }
9576
+ /**
9577
+ * Where this section sits among the assembled prompt's sections.
9578
+ *
9579
+ * DSH concatenates sections in ascending order. The built-in per-tool
9580
+ * narration occupies 1000–3000 and the SDK documentation starts at 5000, so
9581
+ * 3100 is the gap between them. This workflow describes a contributed group of
9582
+ * tools, which is what belongs there: after every built-in tool's narration,
9583
+ * before the SDK reference.
9584
+ */
9585
+ const WORKFLOW_SECTION_ORDER = 3100;
9586
+ /**
9374
9587
  * Register the workflow section.
9375
9588
  *
9376
9589
  * Deferred behind `ctx.inject` rather than declared in this plugin's own
@@ -9383,9 +9596,9 @@ function registerDeployWorkflow(ctx) {
9383
9596
  ctx.inject(["systemPrompt"], (scope) => {
9384
9597
  scope.systemPrompt.section({
9385
9598
  name: WORKFLOW_SECTION_NAME,
9386
- order: scope.systemPrompt.getSectionOrder("MCP_SERVERS"),
9599
+ order: WORKFLOW_SECTION_ORDER,
9387
9600
  interpolate: false,
9388
- text: ({ scope: renderScope }) => ctx.tools.get("aishell__terraform_apply", renderScope) === void 0 ? "" : DEPLOY_WORKFLOW
9601
+ text: ({ scope: renderScope }) => buildDeployWorkflow((name$1) => ctx.tools.get(name$1, renderScope) !== void 0)
9389
9602
  });
9390
9603
  });
9391
9604
  }
@@ -9448,8 +9661,8 @@ function apply(ctx, config) {
9448
9661
  const { registrar, captured } = createRegistrar();
9449
9662
  registerAllTools(registrar);
9450
9663
  const workingDirectory = () => ctx.get("workingDirectory");
9451
- const disposers = captured.map((tool) => {
9452
- const definition = toToolDefinition(tool, config.toolCallTimeoutMs.get(), { ensure: (agent, signal) => requireSessionDirectories(workingDirectory()).ensure(agent, signal) });
9664
+ const disposers = captured.map((tool$1) => {
9665
+ const definition = toToolDefinition(tool$1, config.toolCallTimeoutMs.get(), { ensure: (agent, signal) => requireSessionDirectories(workingDirectory()).ensure(agent, signal) });
9453
9666
  return ctx.tools.register(definition);
9454
9667
  });
9455
9668
  ctx.effect(() => () => {
@@ -27,7 +27,7 @@
27
27
  *
28
28
  * @module @huaweidevtools/aishell-dsh-deploy/d2-inventory
29
29
  */
30
- import type { InventoryTopology } from './existing-topology.ts';
30
+ import type { InventoryEdge, InventoryTopology } from './existing-topology.ts';
31
31
  import type { RenderResult } from './d2-engine.ts';
32
32
  /**
33
33
  * The class for one provider/type pair, stable across runs and pictures.
@@ -51,4 +51,32 @@ export declare function renderInventoryTopology(topology: InventoryTopology): Pr
51
51
  * @returns D2 source text.
52
52
  */
53
53
  export declare function inventoryToD2(topology: InventoryTopology): string;
54
+ /**
55
+ * The relationships worth drawing as an arrow.
56
+ *
57
+ * Three kinds of association are dropped, each for a reason that shows up on a
58
+ * real account rather than being a preference:
59
+ *
60
+ * 1. **Containment.** A parent/child edge is already said by the nesting, and
61
+ * an arrow beside it draws the same fact twice — the line leaves the box
62
+ * it never left.
63
+ * 2. **The reverse of another edge.** The inventory reports both ends of a
64
+ * relationship: an EIP names its bandwidth and the bandwidth names the
65
+ * EIP, a server names its volumes and each volume names the server. Both
66
+ * are true, but one arrow per pair says as much and does not put two
67
+ * lines on top of each other. Measured on a live 49-resource account:
68
+ * 40 associations, 32 distinct pairs.
69
+ * 3. **A reference that points at an ancestor.** The VPC a resource sits in
70
+ * is visible from where the resource is drawn; a line from inside the
71
+ * container out to it adds no fact and crosses the container's border to
72
+ * say nothing. Five of those on the same account, all of them `vpc_id`.
73
+ *
74
+ * What is left is a genuine cross-container reference: a resource here naming
75
+ * a resource there. Those are the ones a reader has to follow, so they are the
76
+ * ones that get a line.
77
+ *
78
+ * @param topology - the derived picture.
79
+ * @returns the edges to draw, deduplicated and without the ones nesting implies.
80
+ */
81
+ export declare function drawnEdges(topology: InventoryTopology): readonly InventoryEdge[];
54
82
  //# sourceMappingURL=d2-inventory.d.ts.map
@@ -27,7 +27,7 @@
27
27
  *
28
28
  * Reference counts cannot answer "what contains what". A rule built on them —
29
29
  * a container is a type that receives references and makes none back — fails
30
- * three ways, every one of them observable on a real account:
30
+ * three ways, each of them checkable against a live account:
31
31
  *
32
32
  * 1. **It cannot nest three levels.** A server names both its subnet and its
33
33
  * VPC; the subnet names the VPC. Each of those is a reference into a
@@ -1,19 +1,42 @@
1
1
  /**
2
2
  * What the model reads about how to use this plugin's tools.
3
3
  *
4
- * ## Why a prompt section and not just tool descriptions
4
+ * ## What belongs here, and what belongs in a tool description
5
5
  *
6
- * Eighteen tools each say what they do. None of them says what *order* to
7
- * call them in, or where a person has to approve before the next step runs.
8
- * That knowledge is the difference between a model that can drive a deployment
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.
6
+ * The boundary is one sentence: **a description answers "what happens if I call
7
+ * this tool"; this section answers "what do I do next, and when must I stop and
8
+ * ask".**
12
9
  *
13
- * The section also carries the constraint the tools cannot express: several
14
- * steps require explicit user consent before proceeding, and a tool description
15
- * is the wrong place to say so — the model reads descriptions once while
16
- * deciding which tool to call, not at the moment it is about to act.
10
+ * Three things follow, and they decide where each piece of text lives:
11
+ *
12
+ * - **No single tool knows the order.** Which call comes before which is a
13
+ * fact about the set, and a description that restated it would be a second
14
+ * copy to keep in step — one that reads as authoritative while being the
15
+ * stale one.
16
+ * - **No tool can enforce consent.** `plan_gate.ts` says so itself: whether a
17
+ * person actually looked at the plan is not observable from inside the
18
+ * process. A description saying "MUST confirm" claims a guarantee the tool
19
+ * does not have; getting the agreement is the step, so it belongs here.
20
+ * - **A description must still state what the tool itself refuses**, because
21
+ * that is behaviour: `terraform_apply`'s five gates, `terraform_destroy`'s
22
+ * target match, `validate_design`'s refusal to draw a non-network
23
+ * configuration. A model that cannot predict a refusal reports it as a bug.
24
+ *
25
+ * ## Why the text is assembled rather than fixed
26
+ *
27
+ * DSH sends the full tool list on every request, so both this section and the
28
+ * descriptions are always in context. What decides the design is not frequency
29
+ * but scope: this section describes a workflow across many tools, and an agent
30
+ * whose toolset was narrowed still reads whatever is here.
31
+ *
32
+ * A fixed string can only be shown or hidden as a whole, so hiding it for one
33
+ * missing tool hides it for every tool that is still there. An agent holding
34
+ * `list_existing_resources` and `validate_design` with no instructions is worse
35
+ * off than one holding none at all, because the tools look usable.
36
+ *
37
+ * So each block declares the tools it is about, and a block whose tools are not
38
+ * all present is dropped. Steps renumber themselves, so a shortened workflow
39
+ * still reads as a sequence rather than as missing numbers.
17
40
  *
18
41
  * ## Why `section()` and not `context()`
19
42
  *
@@ -23,12 +46,21 @@
23
46
  * A section is part of the assembled prompt, so it is in front of the model at
24
47
  * every step.
25
48
  *
26
- * ## Order
49
+ * ## Where it sits in the assembled prompt
50
+ *
51
+ * The assembled prompt is a fixed sequence of ordered slots. The built-in
52
+ * per-tool narration occupies 1000–3000 and the SDK documentation starts at
53
+ * 5000, so 3100 is the gap reserved for guidance contributed by an outside
54
+ * source — which is what a section describing a group of contributed tools is.
27
55
  *
28
- * `MCP_SERVERS` (3100) — after every built-in tool section, before `TOOLS_SDK`.
29
- * That is where the assembled prompt places server-contributed tool guidance,
30
- * and this is exactly that: guidance for a group of contributed tools. A number
31
- * rather than a name is not needed here; the table has a slot for it.
56
+ * Anything earlier would read as a built-in tool's own narration; anything
57
+ * later would land among the SDK reference. A section that is policy rather
58
+ * than guidance belongs in `context()` instead, which is what the read-only
59
+ * switch uses.
60
+ *
61
+ * The name is used rather than the number: the framework owns the ordering, and
62
+ * a hard-coded 3100 would drift from it silently the first time a built-in tool
63
+ * section is added.
32
64
  *
33
65
  * @module @huaweidevtools/aishell-dsh-deploy/prompt
34
66
  */
@@ -36,17 +68,12 @@ import type { Context } from '@deepseek-ai/cordis';
36
68
  /** Name this contribution registers under; unique across the assembled prompt. */
37
69
  export declare const WORKFLOW_SECTION_NAME = "aishell:deploy-workflow";
38
70
  /**
39
- * What the model reads.
40
- *
41
- * Written in English like every other host-side string in this repo — prompt
42
- * sections are host text, and the browser half owns localized copy. The model
43
- * relays the answer in the user's language; the instructions do not need to
44
- * change language to do that.
71
+ * The workflow text for one render scope.
45
72
  *
46
- * Every tool name appears as the model sees it, `aishell__<name>`, so a model
47
- * can copy it straight into a call.
73
+ * @param present - whether a tool with the given name is registered here.
74
+ * @returns the section's text, empty when nothing it describes is available.
48
75
  */
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\".";
76
+ export declare function buildDeployWorkflow(present: (name: string) => boolean): string;
50
77
  /**
51
78
  * Register the workflow section.
52
79
  *
@@ -1,9 +1,13 @@
1
1
  /**
2
2
  * The version recorded in a deployment's `.deployment.json`.
3
3
  *
4
- * A deployment snapshot names the code that wrote it, so an old workspace can
5
- * be traced to the path that produced it. This plugin's version is the honest
6
- * value: there is no separate build to name.
4
+ * GENERATED by `scripts/write-deploy-version.mjs` — do not edit. It is
5
+ * rewritten on every build from the package manifest, so the two cannot
6
+ * disagree; a hand-written value here would drift from the version that
7
+ * actually ships, and the field exists to make that traceable.
8
+ *
9
+ * A deployment snapshot names the code that wrote it, so an old workspace can be
10
+ * traced to the release that produced it.
7
11
  *
8
12
  * @module @huaweidevtools/aishell-dsh-deploy/version
9
13
  */
@@ -14,5 +18,5 @@
14
18
  * written by earlier releases carry it — so it is kept even though there is no
15
19
  * server.
16
20
  */
17
- export declare const SERVER_VERSION = "aishell-deploy 0.1.0";
21
+ export declare const SERVER_VERSION = "aishell-deploy 0.0.18";
18
22
  //# sourceMappingURL=version.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@huaweidevtools/aishell-dsh-deploy",
3
3
  "description": "Huawei Cloud infrastructure tools for DSH — Terraform, OpenAPI, resource inventory, cost estimates",
4
- "version": "0.0.17",
4
+ "version": "0.0.18",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -32,7 +32,7 @@
32
32
  "hcl2-parser": "^1.0.3",
33
33
  "jsonpath-plus": "^10.4.0",
34
34
  "zod": "^4.2.0",
35
- "@huaweidevtools/aishell-dsh-credentials-store": "0.0.17"
35
+ "@huaweidevtools/aishell-dsh-credentials-store": "0.0.18"
36
36
  },
37
37
  "peerDependencies": {
38
38
  "@deepseek-ai/cordis": "^4.0.4",
@@ -59,6 +59,6 @@
59
59
  }
60
60
  },
61
61
  "scripts": {
62
- "build:bundle": "tsdown && node ../../scripts/build-deploy-data.mjs"
62
+ "build:bundle": "node ../../scripts/write-deploy-version.mjs && tsdown && node ../../scripts/build-deploy-data.mjs"
63
63
  }
64
64
  }