@huaweidevtools/aishell-dsh-deploy 0.0.19 → 0.0.21

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.
@@ -0,0 +1,105 @@
1
+ /**
2
+ * How traffic reaches the account, read from what the inventory reports.
3
+ *
4
+ * ## What a path is, and why these three kinds
5
+ *
6
+ * A path is a chain of resources where each one hands traffic to the next. The
7
+ * inventory reports three such handoffs, and they are the only ones it reports:
8
+ *
9
+ * - **Public entry** — an EIP names the instance it is attached to
10
+ * (`associateInstanceId`). That is the point where traffic from outside the
11
+ * account meets something inside it.
12
+ * - **Load balancer front end** — a listener names its balancer
13
+ * (`loadbalancers[].id`) and carries the protocol and port it answers on.
14
+ * That is where a request picks its port.
15
+ * - **Balancer back end** — a Kubernetes-managed listener carries the cluster
16
+ * it fronts in its `description`, as JSON. That is the hop from "a port is
17
+ * open" to "these pods are behind it".
18
+ *
19
+ * A chain is assembled by matching a resource's id against the ids other
20
+ * resources name — the same rule the rest of the picture uses. Nothing here is
21
+ * keyed by a service name, so a service that reports the same handoff the same
22
+ * way joins a path without a line of code.
23
+ *
24
+ * ## What it deliberately does not claim
25
+ *
26
+ * It does not infer a hop the data does not state. A server with no recorded
27
+ * address is not assumed to sit behind a balancer, and a balancer's pool is not
28
+ * followed to its members: the inventory lists the pool's id but not its
29
+ * members, so the members are a separate query away. A picture that guessed
30
+ * those would show a flow nobody verified.
31
+ *
32
+ * @module @huaweidevtools/aishell-dsh-deploy/traffic
33
+ */
34
+ import type { AccountResource } from './account-view.ts';
35
+ /** One hop of a path. */
36
+ export interface Hop {
37
+ /** What kind of thing this hop is, for the renderer's wording. */
38
+ readonly kind: 'internet' | 'eip' | 'balancer' | 'listener' | 'target';
39
+ /** The resource id, or `undefined` for the internet itself. */
40
+ readonly id: string | undefined;
41
+ /** The address or port that makes this hop concrete, when there is one. */
42
+ readonly detail: string | undefined;
43
+ }
44
+ /** A chain from outside the account to something inside it. */
45
+ export interface TrafficPath {
46
+ readonly hops: readonly Hop[];
47
+ }
48
+ /**
49
+ * The cluster a listener fronts, when the listener says so.
50
+ *
51
+ * A listener created by the Kubernetes integration records its owner as JSON in
52
+ * `description` — `{"cluster_id": "…", "service_id": "…"}`. That is the only
53
+ * place the hop from the load balancer to the cluster is written down.
54
+ *
55
+ * @param resource - a listener.
56
+ * @returns the cluster id, or `undefined` when the listener is not owned by one.
57
+ */
58
+ export declare function clusterBehind(resource: AccountResource): string | undefined;
59
+ /**
60
+ * Every path the inventory states.
61
+ *
62
+ * @param resources - the account's resources.
63
+ * @returns the paths, each starting at the internet.
64
+ */
65
+ export declare function trafficPaths(resources: readonly AccountResource[]): TrafficPath[];
66
+ /**
67
+ * Continue a chain past its last box, through the policy that admits it.
68
+ *
69
+ * ## The gap this closes, and the limit of closing it
70
+ *
71
+ * A Kubernetes listener records the cluster it fronts, and nothing further: the
72
+ * inventory does not say which pods talk to which database. What it DOES say is
73
+ * that one group admits another on a port, and which resources each group
74
+ * guards — so a cluster guarded by group A, where A's peer group B admits the
75
+ * database, is a flow the account actually states.
76
+ *
77
+ * That is a hop through a rule rather than through a resource, and it is the
78
+ * only continuation the data supports. It is added only when exactly one group
79
+ * admits exactly one guarded target: with several candidates the chain would be
80
+ * a guess, and a guess drawn as a flow is the defect this module exists to
81
+ * avoid.
82
+ *
83
+ * @param resources - the account's resources.
84
+ * @param view - the resolved layers.
85
+ * @returns extra hops, keyed by the resource a chain currently ends at.
86
+ */
87
+ export declare function policyContinuations(resources: readonly AccountResource[], view: {
88
+ readonly guardsOf: ReadonlyMap<string, readonly string[]>;
89
+ readonly policies: readonly {
90
+ readonly from: string;
91
+ readonly to: string;
92
+ readonly direction: string;
93
+ readonly protocol: string;
94
+ readonly ports: string | undefined;
95
+ }[];
96
+ }): Map<string, Hop>;
97
+ /**
98
+ * The name of what a path ends at, for a caption.
99
+ *
100
+ * @param path - the path.
101
+ * @param resources - the account's resources.
102
+ * @returns the last hop's name, or an empty string when it names nothing.
103
+ */
104
+ export declare function pathTarget(path: TrafficPath, resources: readonly AccountResource[]): string;
105
+ //# sourceMappingURL=traffic.d.ts.map
@@ -18,5 +18,5 @@
18
18
  * written by earlier releases carry it — so it is kept even though there is no
19
19
  * server.
20
20
  */
21
- export declare const SERVER_VERSION = "aishell-deploy 0.0.19";
21
+ export declare const SERVER_VERSION = "aishell-deploy 0.0.21";
22
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.19",
4
+ "version": "0.0.21",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -27,27 +27,26 @@
27
27
  ],
28
28
  "license": "Apache-2.0",
29
29
  "dependencies": {
30
- "@terrastruct/d2": "^0.1.33",
31
30
  "adm-zip": "^0.6.1",
32
31
  "hcl2-parser": "^1.0.3",
33
32
  "jsonpath-plus": "^10.4.0",
34
33
  "zod": "^4.2.0",
35
- "@huaweidevtools/aishell-dsh-credentials-store": "0.0.19"
34
+ "@huaweidevtools/aishell-dsh-credentials-store": "0.0.21"
36
35
  },
37
36
  "peerDependencies": {
38
37
  "@deepseek-ai/cordis": "^4.0.4",
39
- "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
40
- "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
41
- "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
42
- "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1"
38
+ "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
39
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
40
+ "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
41
+ "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2"
43
42
  },
44
43
  "devDependencies": {
45
44
  "@deepseek-ai/cordis": "^4.0.4",
46
45
  "@deepseek-ai/cordis-plugin-loader": "^1.0.5",
47
- "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
48
- "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
49
- "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
50
- "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1",
46
+ "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
47
+ "@deepseek-ai/dsh-llm": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
48
+ "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
49
+ "@deepseek-ai/dsh-tools": "0.2.0-rc.1 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-rc.1 || 0.2.2-rc.2",
51
50
  "@deepseek-ai/schemastery": "3.18.4",
52
51
  "tsdown": "^0.10.0",
53
52
  "typescript": "^5.7.0",
@@ -1,60 +0,0 @@
1
- /**
2
- * Drawing a design: what a `.tf` declares, with the resources it reuses marked.
3
- *
4
- * ## Why this module does have a table of kinds
5
- *
6
- * Its input is `Topology`, whose nodes have already been classified into a
7
- * design vocabulary (`vpc`, `subnet`, `security-group`, …). That
8
- * classification is the point of the design path: a design is a network
9
- * configuration, and the picture is about the network it declares. A resource
10
- * outside that vocabulary is reported by name rather than drawn — see
11
- * `topology.ts`.
12
- *
13
- * So the tables here map that closed vocabulary onto colour and words. They are
14
- * finite because the input is finite, and a kind added to `NodeKind` without a
15
- * class here fails at generation, naming the fragment.
16
- *
17
- * An account that already exists draws through `d2-inventory.ts` instead, where
18
- * the vocabulary has no closed form.
19
- *
20
- * ## What D2 carries
21
- *
22
- * The PICTURE. Not data: an attribute written as a child (`cidr: "10.0.0.0/16"`)
23
- * becomes a visible second box, so facts go into the node's LABEL instead. A
24
- * mistyped attribute or an edge to an undefined node is accepted silently.
25
- *
26
- * @module @huaweidevtools/aishell-dsh-deploy/d2-design
27
- */
28
- import type { Topology, TopologyEdge } from './topology.ts';
29
- import type { RenderResult } from './d2-engine.ts';
30
- /**
31
- * Draw the topology.
32
- *
33
- * @param topology - the derived picture.
34
- * @param edges - the relationships to draw, from `<from-address>` to
35
- * `<to-address>`. Only addresses the topology knows are drawn.
36
- * @returns the D2 source and the SVG it renders to.
37
- * @throws when the generated D2 source does not compile. That is a defect in
38
- * this module rather than in the user's configuration — the generator is
39
- * what produced the text — so the message names the generated fragment.
40
- */
41
- export declare function renderTopology(topology: Topology, edges: readonly TopologyEdge[]): Promise<RenderResult>;
42
- /**
43
- * Generate the D2 source for one topology.
44
- *
45
- * The shape of the output is fixed by what D2 accepts:
46
- *
47
- * - Nothing is written as an attribute child. `cidr: "10.0.0.0/16"` inside a
48
- * node's block renders as its own box, which would put a stray rectangle
49
- * in every subnet. Facts go into the node's LABEL instead.
50
- * - Facts are separated by `·` rather than aligned into columns, because D2
51
- * treats a leading `|` as a block-string terminator.
52
- * - No `vars` block beyond the theme: D2 discards everything under it except
53
- * `d2-config`.
54
- *
55
- * @param topology - the derived picture.
56
- * @param edges - the relationships to draw.
57
- * @returns D2 source text.
58
- */
59
- export declare function toD2(topology: Topology, edges: readonly TopologyEdge[]): string;
60
- //# sourceMappingURL=d2-design.d.ts.map
@@ -1,137 +0,0 @@
1
- /**
2
- * The D2 renderer itself: source text in, SVG out.
3
- *
4
- * ## What this module owns, and what it does not
5
- *
6
- * It owns the mechanism — instantiating the WASM build, compiling, rendering,
7
- * and handing the linear memory back. It knows nothing about topology: the
8
- * source text it is given could draw anything.
9
- *
10
- * That separation is why there are two topology modules beside it
11
- * (`d2-design.ts` and `d2-inventory.ts`). They generate different source from
12
- * different inputs, and neither is a mode of the other; putting both in one file
13
- * made a module whose reader could not tell which rules applied to which
14
- * picture.
15
- *
16
- * ## Why D2 at all
17
- *
18
- * A network topology is a nested graph with edges, and every hand-rolled layout
19
- * for one has to solve two things badly: where a box goes, and where its edges
20
- * land. D2 solves both, and it is the format's own vocabulary — containers
21
- * nest, arrows connect, `near:` pins an annotation panel.
22
- *
23
- * The cost is real and worth stating: the WASM build is ~21 MB packaged, and
24
- * the compile step instantiates it once per process (~1.1 s cold, then ~70 ms
25
- * per diagram). It runs inside a worker thread that D2 owns, so the
26
- * instantiation does not block this process's event loop; {@link closeD2}
27
- * terminates that worker, which is the only way to hand the ~600 MB of WASM
28
- * linear memory back.
29
- *
30
- * ## What D2 does and does not carry
31
- *
32
- * It carries the PICTURE. It does not carry data: custom `vars` are discarded,
33
- * an attribute written as a child (`cidr: "10.0.0.0/16"`) becomes a visible
34
- * second box, and a mistyped attribute or an edge to an undefined node are
35
- * accepted silently. So nothing is ever read back out of D2 — a topology is
36
- * derived from its own source and D2 is only where it is drawn. That direction
37
- * matters: a generator is exact, a parser of pictures is not.
38
- *
39
- * @module @huaweidevtools/aishell-dsh-deploy/d2-engine
40
- */
41
- /**
42
- * The D2 themes, light and dark.
43
- *
44
- * Theme 5 rather than 0 for light. Theme 0 collapses its accent ramps into one
45
- * blue-grey: `B`, `AA` and `AB` all resolve to shades of `#EDF0FD`/`#F7F8FE`
46
- * there, so a diagram styled with three kinds of box draws three boxes in one
47
- * colour. Theme 5 keeps them apart — blue, violet, pink (measured against the
48
- * rendered palette, not the docs).
49
- *
50
- * 201 rather than 200 for dark, for the same reason and by the same measurement:
51
- * 200 collapses the same way (`B2` and `AA2` both `#CBA6f7`), 201 keeps a
52
- * distinguishable blue/violet/teal.
53
- *
54
- * Both ids must be given. With no `dark-theme-id` D2 emits NO dark palette at
55
- * all, and every class would resolve in light colours on a dark ground.
56
- */
57
- export declare const LIGHT_THEME_ID = 5;
58
- export declare const DARK_THEME_ID = 201;
59
- /** One render in, one render out; the caller owns timing and disposal. */
60
- export interface RenderResult {
61
- /** The D2 source that was rendered, so a reader can see what was drawn. */
62
- readonly source: string;
63
- /** The SVG, with no XML declaration so it embeds directly in HTML. */
64
- readonly svg: string;
65
- }
66
- /**
67
- * The `vars` block every generated diagram opens with.
68
- *
69
- * The theme ids are written into the diagram rather than passed to `render`, so
70
- * the generated source is the whole description of what was drawn — a reader
71
- * feeding it to the D2 CLI gets the same colours.
72
- *
73
- * @returns the opening lines of a D2 document.
74
- */
75
- export declare function themePreamble(): string[];
76
- /**
77
- * Compile D2 source and render it to an SVG.
78
- *
79
- * @param source - the D2 source text.
80
- * @returns the SVG, with no XML declaration.
81
- * @throws when the source does not compile. That is a defect in the generator
82
- * rather than in the user's configuration — the generator produced the text —
83
- * so the caller names the generated fragment in its message.
84
- */
85
- export declare function renderD2(source: string): Promise<string>;
86
- /**
87
- * Give the outer `<svg>` an intrinsic size.
88
- *
89
- * ## Why this is not cosmetic
90
- *
91
- * D2 emits the outer element with a `viewBox` and no `width`/`height`. In CSS,
92
- * an SVG with no intrinsic dimensions is a replaced element with no size, and
93
- * the browser falls back to 300×150 — then scales the whole `viewBox` into that
94
- * box. A picture of a real account is around 5000×1800, so the scale factor is
95
- * roughly 0.06 and a 16px label is drawn at about 1px: the diagram renders, and
96
- * is unreadable at any preview size.
97
- *
98
- * That is not a layout problem to tune — the file is correct, and it has no
99
- * size of its own. Declaring one gives the browser something to lay out at its
100
- * natural dimensions; whatever container shows it can then scale a legible
101
- * image down rather than a legible image already scaled to nothing.
102
- *
103
- * The values come from the viewBox, which is what D2 computed from the content,
104
- * so nothing is guessed. A viewBox D2 did not emit is left alone: a wrong size
105
- * would be worse than the default, and the caller's render would be reported
106
- * as broken for a reason that is not theirs.
107
- *
108
- * @param svg - the rendered SVG.
109
- * @returns the same SVG with `width` and `height` on the outer element.
110
- */
111
- export declare function withIntrinsicSize(svg: string): string;
112
- /**
113
- * Quote a string for a D2 label.
114
- *
115
- * @param text - the label.
116
- * @returns the text inside double quotes, with its own quotes escaped.
117
- */
118
- export declare function quote(text: string): string;
119
- /**
120
- * The D2 identifier for an address or cloud id.
121
- *
122
- * A `.` in a D2 key means "member of the block before it", so an unreplaced one
123
- * nests the node inside a box named after the part before the dot — inventing a
124
- * container that does not exist. Every character D2 reserves is replaced by `_`
125
- * for the same reason.
126
- *
127
- * A collision is possible in principle (`a_b.c` and `a.b_c` both map to
128
- * `a_b_c`). It cannot occur inside one provider namespace, where the separator
129
- * between resource types and names is always the same `.`, but callers draw
130
- * from a map keyed by the original id, so a collision would drop an edge rather
131
- * than misplace it.
132
- *
133
- * @param address - a terraform `type.name` address or a cloud resource id.
134
- * @returns an identifier D2 accepts.
135
- */
136
- export declare function d2Id(address: string): string;
137
- //# sourceMappingURL=d2-engine.d.ts.map
@@ -1,82 +0,0 @@
1
- /**
2
- * Drawing an account that already exists.
3
- *
4
- * ## What this module is given, and what it is not
5
- *
6
- * Its input is `InventoryTopology`: nodes carrying the raw `provider`/`type`
7
- * the inventory reported, and edges carrying the attribute that established
8
- * them. Nothing here has been translated into a design vocabulary first, which
9
- * is why nothing here needs a table of kinds — the picture can contain a
10
- * service this deployment has never seen.
11
- *
12
- * ## Colour
13
- *
14
- * A table of types would need a line per service and would be wrong the first
15
- * time an unfamiliar one appeared. Colouring by provider alone is not enough
16
- * either: a picture of one VPC and nine security groups then reads as ten of
17
- * the same thing.
18
- *
19
- * So the provider picks the hue and the type picks the lightness step inside it:
20
- * resources of one service read as a family, and different types inside it stay
21
- * apart. Both are D2's own theme classes, so the dark palette follows with no
22
- * JavaScript.
23
- *
24
- * The mapping is a hash rather than an assignment, for the same reason: a table
25
- * that assigned a hue per service would need a new line for every service, and
26
- * a service missing from it would draw in whatever the fallback happened to be.
27
- *
28
- * @module @huaweidevtools/aishell-dsh-deploy/d2-inventory
29
- */
30
- import type { InventoryEdge, InventoryTopology } from './existing-topology.ts';
31
- import type { RenderResult } from './d2-engine.ts';
32
- /**
33
- * The class for one provider/type pair, stable across runs and pictures.
34
- *
35
- * @param provider - the service that reported the resource.
36
- * @param type - that service's own type name.
37
- * @returns a D2 theme class reference.
38
- */
39
- export declare function inventoryClass(provider: string, type: string): string;
40
- /**
41
- * Draw an inventory-derived topology.
42
- *
43
- * @param topology - the picture derived from the inventory.
44
- * @returns the D2 source and the SVG it renders to.
45
- */
46
- export declare function renderInventoryTopology(topology: InventoryTopology): Promise<RenderResult>;
47
- /**
48
- * Generate the D2 source for an inventory-derived topology.
49
- *
50
- * @param topology - the picture.
51
- * @returns D2 source text.
52
- */
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[];
82
- //# sourceMappingURL=d2-inventory.d.ts.map