@huaweidevtools/aishell-dsh-deploy 0.0.16 → 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/README.md +4 -1
- package/lib/index.js +1394 -361
- package/lib/types/bridge.d.ts +16 -1
- package/lib/types/d2-design.d.ts +60 -0
- package/lib/types/d2-engine.d.ts +111 -0
- package/lib/types/d2-inventory.d.ts +82 -0
- package/lib/types/existing-topology.d.ts +154 -0
- package/lib/types/existing.d.ts +28 -7
- package/lib/types/gates/terraform_env.d.ts +1 -1
- package/lib/types/inventory-subnets.d.ts +78 -0
- package/lib/types/paths.d.ts +51 -0
- package/lib/types/projects.d.ts +40 -0
- package/lib/types/prompt.d.ts +52 -25
- package/lib/types/types.d.ts +28 -3
- package/lib/types/version.d.ts +8 -4
- package/package.json +3 -3
- package/lib/types/d2-render.d.ts +0 -74
package/lib/types/prompt.d.ts
CHANGED
|
@@ -1,19 +1,42 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* What the model reads about how to use this plugin's tools.
|
|
3
3
|
*
|
|
4
|
-
* ##
|
|
4
|
+
* ## What belongs here, and what belongs in a tool description
|
|
5
5
|
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
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
|
-
* ##
|
|
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
|
-
*
|
|
29
|
-
*
|
|
30
|
-
*
|
|
31
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
47
|
-
*
|
|
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 ``. 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
|
*
|
package/lib/types/types.d.ts
CHANGED
|
@@ -42,11 +42,36 @@ export interface CallToolResult {
|
|
|
42
42
|
/**
|
|
43
43
|
* Per-call context handed to a handler.
|
|
44
44
|
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
45
|
+
* ## Why the session directory is here
|
|
46
|
+
*
|
|
47
|
+
* Every tool in this plugin takes a `deployment` path, and a caller may give it
|
|
48
|
+
* relatively — the model writes "huawei-topology" because that is the directory
|
|
49
|
+
* it just made. A relative path has to resolve against *something*, and the
|
|
50
|
+
* default Node and the harness differ on what:
|
|
51
|
+
*
|
|
52
|
+
* - Node resolves it against `process.cwd()`, the directory the host was
|
|
53
|
+
* launched from. That has nothing to do with the working directory the
|
|
54
|
+
* person picked for this session.
|
|
55
|
+
* - Every filesystem tool in the product resolves it against the session's
|
|
56
|
+
* working directory, which is what a person means by "here".
|
|
57
|
+
*
|
|
58
|
+
* Two tools disagreeing about what "huawei-topology" names is exactly the
|
|
59
|
+
* failure that produces a workspace nobody can find, so this plugin anchors at
|
|
60
|
+
* the session like everything else does.
|
|
61
|
+
*
|
|
62
|
+
* The field is optional because the service may not be mounted. Its absence is
|
|
63
|
+
* not permission to fall back to `process.cwd()`: a relative path then has no
|
|
64
|
+
* correct meaning, and the tool says so. `undefined` is a fact to report, not a
|
|
65
|
+
* default to invent.
|
|
48
66
|
*/
|
|
49
67
|
export interface ToolContext {
|
|
68
|
+
/**
|
|
69
|
+
* The session's absolute working directory, when the host provides one.
|
|
70
|
+
*
|
|
71
|
+
* Absolute and already validated by the host — it restores the original
|
|
72
|
+
* directory when the one the person picked has been removed.
|
|
73
|
+
*/
|
|
74
|
+
readonly sessionDirectory?: string;
|
|
50
75
|
}
|
|
51
76
|
/** The context type the tool modules name. */
|
|
52
77
|
export type ToolCtx = ToolContext;
|
package/lib/types/version.d.ts
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The version recorded in a deployment's `.deployment.json`.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
* value
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
}
|
package/lib/types/d2-render.d.ts
DELETED
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Drawing the topology: D2 source, then an SVG.
|
|
3
|
-
*
|
|
4
|
-
* ## Why D2 and not hand-built SVG
|
|
5
|
-
*
|
|
6
|
-
* A network topology is a nested graph with edges, and every hand-rolled
|
|
7
|
-
* layout for one has to solve two things badly: where a box goes, and where
|
|
8
|
-
* its edges land. D2 solves both, and it is the format's own vocabulary —
|
|
9
|
-
* containers nest, arrows connect, `near:` pins an annotation panel.
|
|
10
|
-
*
|
|
11
|
-
* The cost is real and worth stating: the WASM build is ~21 MB packaged, and
|
|
12
|
-
* the compile step instantiates it once per process (~1.1 s cold, then ~70 ms
|
|
13
|
-
* per diagram). It runs inside a worker thread that D2 owns, so the
|
|
14
|
-
* instantiation does not block this process's event loop; {@link closeD2}
|
|
15
|
-
* terminates that worker, which is the only way to hand the ~600 MB of WASM
|
|
16
|
-
* linear memory back.
|
|
17
|
-
*
|
|
18
|
-
* ## What D2 does and does not carry
|
|
19
|
-
*
|
|
20
|
-
* It carries the PICTURE. It does not carry data: custom `vars` are discarded,
|
|
21
|
-
* an attribute written as a child (`cidr: "10.0.0.0/16"`) becomes a visible
|
|
22
|
-
* second box, and a mistyped attribute or an edge to an undefined node are
|
|
23
|
-
* accepted silently. So nothing here is read back out of D2 — the topology is
|
|
24
|
-
* derived from HCL and D2 is only where it is drawn. That direction matters:
|
|
25
|
-
* a generator is exact, a parser of pictures is not.
|
|
26
|
-
*
|
|
27
|
-
* ## Theme
|
|
28
|
-
*
|
|
29
|
-
* `render` is given both `themeID` and `darkThemeID`; D2 emits both palettes
|
|
30
|
-
* into one SVG and selects between them with `@media
|
|
31
|
-
* (prefers-color-scheme: dark)`. The result follows the viewer's setting with
|
|
32
|
-
* no JavaScript.
|
|
33
|
-
*
|
|
34
|
-
* @module @huaweidevtools/aishell-dsh-deploy/d2-render
|
|
35
|
-
*/
|
|
36
|
-
import type { Topology, TopologyEdge } from './topology.ts';
|
|
37
|
-
/** One render in, one render out; the caller owns timing and disposal. */
|
|
38
|
-
export interface RenderResult {
|
|
39
|
-
/** The D2 source that was rendered, so a reader can see what was drawn. */
|
|
40
|
-
readonly source: string;
|
|
41
|
-
/** The SVG, with no XML declaration so it embeds directly in HTML. */
|
|
42
|
-
readonly svg: string;
|
|
43
|
-
}
|
|
44
|
-
/**
|
|
45
|
-
* Draw the topology.
|
|
46
|
-
*
|
|
47
|
-
* @param topology - the derived picture.
|
|
48
|
-
* @param edges - the relationships to draw, from `<from-address>` to
|
|
49
|
-
* `<to-address>`. Only addresses the topology knows are drawn.
|
|
50
|
-
* @returns the D2 source and the SVG it renders to.
|
|
51
|
-
* @throws when the generated D2 source does not compile. That is a defect in
|
|
52
|
-
* this module rather than in the user's configuration — the generator is
|
|
53
|
-
* what produced the text — so the message names the generated fragment.
|
|
54
|
-
*/
|
|
55
|
-
export declare function renderTopology(topology: Topology, edges: readonly TopologyEdge[]): Promise<RenderResult>;
|
|
56
|
-
/**
|
|
57
|
-
* Generate the D2 source for one topology.
|
|
58
|
-
*
|
|
59
|
-
* The shape of the output is fixed by what D2 accepts, and every choice here
|
|
60
|
-
* comes from something D2 refused:
|
|
61
|
-
*
|
|
62
|
-
* - Nothing is written as an attribute child. `cidr: "10.0.0.0/16"` inside a
|
|
63
|
-
* node's block renders as its own box, which would put a stray rectangle
|
|
64
|
-
* in every subnet. Facts go into the node's LABEL instead.
|
|
65
|
-
* - Facts are separated by `·` rather than aligned into columns, because D2
|
|
66
|
-
* treats a leading `|` as a block-string terminator.
|
|
67
|
-
* - No `vars` block: D2 discards everything under it except `d2-config`.
|
|
68
|
-
*
|
|
69
|
-
* @param topology - the derived picture.
|
|
70
|
-
* @param edges - the relationships to draw.
|
|
71
|
-
* @returns D2 source text.
|
|
72
|
-
*/
|
|
73
|
-
export declare function toD2(topology: Topology, edges: readonly TopologyEdge[]): string;
|
|
74
|
-
//# sourceMappingURL=d2-render.d.ts.map
|