@huaweidevtools/aishell-dsh-deploy 0.0.16 → 0.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -63,8 +63,23 @@ export declare function publicToolName(rawName: string): string;
63
63
  *
64
64
  * @param tool - the captured registration.
65
65
  * @param timeoutMs - per-call budget handed to the harness.
66
+ * @param workingDirectory - the host's session-directory service, when mounted.
66
67
  * @returns the definition to hand to `ctx.tools.register`.
67
68
  */
68
- export declare function toToolDefinition(tool: CapturedTool, timeoutMs: number): ToolDefinition;
69
+ export declare function toToolDefinition(tool: CapturedTool, timeoutMs: number, workingDirectory?: SessionDirectories): ToolDefinition;
70
+ /**
71
+ * The working-directory service, as this plugin needs it.
72
+ *
73
+ * Structural rather than imported, for the reason `aishell-e2b` states: importing
74
+ * the framework package for one method would add a dependency whose own
75
+ * `schemastery` pin differs from this package's, and the duplicate copy leaks
76
+ * into the emitted `.d.ts` through a `.pnpm/…` path nobody installing this
77
+ * package has. One method is all that is used, so one method is all that is
78
+ * declared.
79
+ */
80
+ interface SessionDirectories {
81
+ /** The session's effective absolute directory, validated and restored. */
82
+ readonly ensure: (agent: object, signal?: AbortSignal) => Promise<string>;
83
+ }
69
84
  export {};
70
85
  //# sourceMappingURL=bridge.d.ts.map
@@ -0,0 +1,60 @@
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
@@ -0,0 +1,111 @@
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
+ * Quote a string for a D2 label.
88
+ *
89
+ * @param text - the label.
90
+ * @returns the text inside double quotes, with its own quotes escaped.
91
+ */
92
+ export declare function quote(text: string): string;
93
+ /**
94
+ * The D2 identifier for an address or cloud id.
95
+ *
96
+ * A `.` in a D2 key means "member of the block before it", so an unreplaced one
97
+ * nests the node inside a box named after the part before the dot — inventing a
98
+ * container that does not exist. Every character D2 reserves is replaced by `_`
99
+ * for the same reason.
100
+ *
101
+ * A collision is possible in principle (`a_b.c` and `a.b_c` both map to
102
+ * `a_b_c`). It cannot occur inside one provider namespace, where the separator
103
+ * between resource types and names is always the same `.`, but callers draw
104
+ * from a map keyed by the original id, so a collision would drop an edge rather
105
+ * than misplace it.
106
+ *
107
+ * @param address - a terraform `type.name` address or a cloud resource id.
108
+ * @returns an identifier D2 accepts.
109
+ */
110
+ export declare function d2Id(address: string): string;
111
+ //# sourceMappingURL=d2-engine.d.ts.map
@@ -0,0 +1,54 @@
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 { 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
+ //# sourceMappingURL=d2-inventory.d.ts.map
@@ -0,0 +1,154 @@
1
+ /**
2
+ * The topology of an account that already exists, derived from what the
3
+ * inventory reports.
4
+ *
5
+ * ## What this module knows, and why it is not a table of services
6
+ *
7
+ * The inventory returns resources as `{provider, type, id, name, properties}`.
8
+ * Two different questions are answered from `properties`, and they are not the
9
+ * same kind of question:
10
+ *
11
+ * - **Association.** When one resource's property holds another resource's
12
+ * id, the two are related. That rule needs no vocabulary at all: an id is
13
+ * an id, whatever the service. Associations are drawn as edges.
14
+ * - **Location.** Which resource a box is drawn INSIDE is a fact about the
15
+ * network picture, not about the service that reported it. A network
16
+ * picture is made of networks and their subdivisions — that is what the
17
+ * domain is, in every cloud — so the location vocabulary is those nouns and
18
+ * nothing else: `vpc`, `subnet`.
19
+ *
20
+ * That vocabulary is two words. It is not a per-service table that grows with
21
+ * every service, and it does not name a single service: a service this
22
+ * deployment has never seen gets placed correctly the first time it appears, as
23
+ * long as it says where it lives, because saying where it lives is what makes
24
+ * it placeable.
25
+ *
26
+ * ## Why containment is not derived from the graph
27
+ *
28
+ * Reference counts cannot answer "what contains what". A rule built on them —
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:
31
+ *
32
+ * 1. **It cannot nest three levels.** A server names both its subnet and its
33
+ * VPC; the subnet names the VPC. Each of those is a reference into a
34
+ * container, the deeper placement is never considered, and the server ends
35
+ * up inside the VPC with its subnet beside it — the one arrangement that is
36
+ * wrong.
37
+ * 2. **It makes a security group a container.** A security group receives
38
+ * references and makes none back, which satisfies the rule exactly. A
39
+ * listener that names only a security group lands inside its box.
40
+ * 3. **It depends on a complete graph, and the inventory is not complete.**
41
+ * RMS does not report subnets at all, so the counts a rule needs are
42
+ * missing the very edges that would say "this is a subnet of that VPC".
43
+ *
44
+ * Containment therefore comes from the attribute's own name, which is the
45
+ * provider stating what the relationship is. `vpcId` says "this lives in that
46
+ * VPC"; `securityGroupId` says "this is admitted by that group" — both are
47
+ * references, only one is a location.
48
+ *
49
+ * ## What it deliberately does not do
50
+ *
51
+ * It does not decide that a resource is unimportant. Every resource the
52
+ * inventory returned becomes a node. A diagram that hides things needs a
53
+ * reason to hide them, and a rule for "important" is a table by another name.
54
+ *
55
+ * @module @huaweidevtools/aishell-dsh-deploy/existing-topology
56
+ */
57
+ /** One resource as the inventory reports it. */
58
+ export interface InventoryResource {
59
+ readonly id: string;
60
+ /** The service, e.g. `vpc`, `ecs`, `rds`. */
61
+ readonly provider: string;
62
+ /** The service's own type name, e.g. `vpcs`, `cloudservers`, `securityGroups`. */
63
+ readonly type: string;
64
+ readonly name?: string;
65
+ readonly region?: string;
66
+ readonly properties?: Readonly<Record<string, unknown>>;
67
+ }
68
+ /** One node in the derived picture. */
69
+ export interface InventoryNode {
70
+ /** Stable identity: the cloud resource id. */
71
+ readonly id: string;
72
+ readonly provider: string;
73
+ readonly type: string;
74
+ readonly label: string;
75
+ /** Facts worth showing on the box, already chosen. */
76
+ readonly facts: readonly {
77
+ readonly key: string;
78
+ readonly value: string;
79
+ }[];
80
+ /** The container this node sits in, when one was found. */
81
+ readonly parent: string | undefined;
82
+ /** Every container above this node, nearest first. */
83
+ readonly ancestors: readonly string[];
84
+ readonly children: readonly InventoryNode[];
85
+ }
86
+ /** One relationship between two resources. */
87
+ export interface InventoryEdge {
88
+ readonly from: string;
89
+ readonly to: string;
90
+ /** The attribute that establishes it, e.g. `vnic.vpcId`. */
91
+ readonly attribute: string;
92
+ /**
93
+ * Whether this attribute names a container rather than a peer.
94
+ *
95
+ * Both are drawn; the distinction decides nesting versus an arrow, and is
96
+ * carried rather than acted on here so a reader can see why a resource was
97
+ * placed where it was.
98
+ */
99
+ readonly contains: boolean;
100
+ }
101
+ /** The whole derived picture. */
102
+ export interface InventoryTopology {
103
+ readonly roots: readonly InventoryNode[];
104
+ readonly nodes: readonly InventoryNode[];
105
+ readonly edges: readonly InventoryEdge[];
106
+ /** Resources that appeared in more than one provider/type bucket. */
107
+ readonly duplicates: readonly string[];
108
+ }
109
+ /**
110
+ * Every scalar the properties contain, keyed by its dotted path.
111
+ *
112
+ * Nested objects and arrays are flattened because the inventory nests ids
113
+ * arbitrarily deep (`vnic.vpcId`, `bandwidth.id`,
114
+ * `security_group_rules[].remote_group_id`), and a rule that only looked at the
115
+ * top level would miss most of the relationships.
116
+ *
117
+ * A JSON-encoded value is also opened, because the inventory sometimes ships one
118
+ * as a string. RDS is the case that was measured: it reports `vpcId` as
119
+ * `"[\"73e76381-…\"]"` and `networkId` as its subnet — a real reference, present
120
+ * and correct, that a plain string comparison never matches. Left closed, the
121
+ * RDS instance floats at the root of the picture with its VPC in plain sight in
122
+ * its own properties.
123
+ *
124
+ * @param value - any property value.
125
+ * @returns path → scalar, for every leaf.
126
+ */
127
+ export declare function flattenProperties(value: unknown): Map<string, string>;
128
+ /**
129
+ * How specific a location an attribute names, 0 when it names none.
130
+ *
131
+ * The tail of the path is what counts: `vnic.vpcId` and `metadata.vpcId` both
132
+ * end in a noun describing the container. Everything before the last dot is the
133
+ * service's own nesting and says nothing about which container this is.
134
+ *
135
+ * The `id`/`uid`/`uuid` suffix is stripped rather than required to be present,
136
+ * because the provider writes all three (`subnet_id`, `subnetId`,
137
+ * `virsubnet_id`) and a rule that demanded one spelling would miss the others.
138
+ * A plural suffix is stripped too: `elb_virsubnet_ids` holds several subnets,
139
+ * and whether the attribute holds one id or a list does not change what it
140
+ * names. Suffix matching, not equality, is what makes `virsubnet` and
141
+ * `subnetwork` land on the same noun.
142
+ *
143
+ * @param attribute - a dotted property path.
144
+ * @returns the rank of the location it names, or 0 for a plain association.
145
+ */
146
+ export declare function locationRank(attribute: string): number;
147
+ /**
148
+ * Derive the picture from what the inventory reported.
149
+ *
150
+ * @param resources - every resource the inventory returned.
151
+ * @returns nodes, edges, and the nesting derived from both.
152
+ */
153
+ export declare function deriveInventoryTopology(resources: readonly InventoryResource[]): InventoryTopology;
154
+ //# sourceMappingURL=existing-topology.d.ts.map
@@ -40,6 +40,8 @@ import { z } from 'zod';
40
40
  export declare const ExistingResourceSchema: z.ZodObject<{
41
41
  id: z.ZodString;
42
42
  type: z.ZodString;
43
+ provider: z.ZodOptional<z.ZodString>;
44
+ properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
43
45
  name: z.ZodOptional<z.ZodString>;
44
46
  parent: z.ZodOptional<z.ZodString>;
45
47
  cidr: z.ZodOptional<z.ZodString>;
@@ -65,15 +67,34 @@ export type ExistingKind = 'vpc' | 'subnet' | 'security-group' | 'security-group
65
67
  */
66
68
  export type TopologyKind = ExistingKind;
67
69
  /**
68
- * The kind one resource takes, when the topology has one for it.
70
+ * What one configured resource is.
69
71
  *
70
- * The terraform spelling is normalised by dropping the `huaweicloud_` prefix,
71
- * and a few types carry a `_v2`/`_v1` suffix that is the same resource. That
72
- * leaves one table rather than two that can disagree.
72
+ * This answers for a `.tf` block, whose type is the provider's own spelling. An
73
+ * account's resources do not come through here: the inventory already knows
74
+ * what each one is, and a table of its vocabulary would grow with every service
75
+ * — see `existing-topology.ts` for how that case is derived instead.
73
76
  *
74
- * @param type - either spelling the caller sent.
75
- * @returns the node kind, or `undefined` when this resource is not part of the
76
- * picture — see the note on the table.
77
+ * @param type - a terraform type (`huaweicloud_vpc`) or the short name the
78
+ * provider's own docs use (`vpc`).
79
+ * @returns the node kind, or `undefined` when the picture has none for it.
77
80
  */
78
81
  export declare function kindOfExisting(type: string): ExistingKind | undefined;
82
+ /**
83
+ * What one described resource is.
84
+ *
85
+ * `type` is resolved on its own, which is the whole answer for a caller that
86
+ * sent a terraform type. A caller that copied an RMS `type` has a plural
87
+ * vocabulary ("vpcs", "cloudservers") that says nothing about what the resource
88
+ * IS — and `instances` is both a database and an API gateway, depending on the
89
+ * provider. So when `provider` is present it is used to disambiguate, and when
90
+ * the pair resolves to nothing the answer is `undefined`: the resource is real
91
+ * but this picture has no box for it.
92
+ *
93
+ * @param resource - the described resource.
94
+ * @returns the kind, or `undefined` when the picture has none for it.
95
+ */
96
+ export declare function kindOfResource(resource: {
97
+ readonly type: string;
98
+ readonly provider?: string | undefined;
99
+ }): ExistingKind | undefined;
79
100
  //# sourceMappingURL=existing.d.ts.map
@@ -22,7 +22,7 @@ export interface ResolvedEnv {
22
22
  * Resolve the terraform binary path + env for a deployment.
23
23
  * Throws if no binary can be found.
24
24
  */
25
- export declare function resolveTerraformEnv(deployment: string, extraEnv?: string[]): Promise<ResolvedEnv>;
25
+ export declare function resolveTerraformEnv(deployment: string | undefined, extraEnv?: string[]): Promise<ResolvedEnv>;
26
26
  /**
27
27
  * Record the binary path `terraform_install` was given.
28
28
  *
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Subnets, which RMS does not report.
3
+ *
4
+ * ## Why this module exists
5
+ *
6
+ * A network picture is a network and its subdivisions. RMS reports one of those
7
+ * two levels: a `service: "vpc"` query comes back with `vpcs`,
8
+ * `securityGroups`, `publicips` and `bandwidths` and no subnets at all —
9
+ * confirmed against a live 49-resource account. So an inventory built only from
10
+ * RMS cannot place a server in its subnet, because the subnet is not in the
11
+ * data to place it in.
12
+ *
13
+ * The VPC API does list them, per region and with the `vpc_id` that puts each
14
+ * one inside its VPC. This module reads that, in the vocabulary the inventory
15
+ * already speaks (`provider: "vpc"`, `type: "subnets"`), so the derivation
16
+ * places them and everything that names them without knowing where they came
17
+ * from.
18
+ *
19
+ * ## Why only subnets
20
+ *
21
+ * The same reasoning would justify reaching for any resource RMS misses, and
22
+ * that is exactly the trap. Subnets are asked for because the picture's own
23
+ * structure has a second level and RMS omits it; a resource RMS omits that the
24
+ * picture has no place for is not a gap, it is something the picture is not
25
+ * about. Adding a service here because it is missing would turn this module
26
+ * into a per-service compatibility list.
27
+ *
28
+ * @module @huaweidevtools/aishell-dsh-deploy/inventory-subnets
29
+ */
30
+ /** One subnet, in the shape the inventory's other resources arrive in. */
31
+ export interface InventorySubnet {
32
+ readonly id: string;
33
+ readonly name: string;
34
+ readonly provider: 'vpc';
35
+ readonly type: 'subnets';
36
+ readonly region: string;
37
+ readonly properties: Readonly<Record<string, unknown>>;
38
+ }
39
+ /** The VPC API's subnet record: only the fields this module reads. */
40
+ interface VpcSubnet {
41
+ readonly id?: unknown;
42
+ readonly name?: unknown;
43
+ readonly cidr?: unknown;
44
+ readonly vpc_id?: unknown;
45
+ readonly gateway_ip?: unknown;
46
+ readonly status?: unknown;
47
+ }
48
+ /**
49
+ * Every subnet the account has in one region.
50
+ *
51
+ * Best-effort by contract: a caller completes an inventory, and a region whose
52
+ * subnets could not be read is worse off without its other resources, not
53
+ * better. So a failure is reported rather than thrown, and the caller decides
54
+ * what to say about it.
55
+ *
56
+ * @param region - the region to list.
57
+ * @returns the subnets, or the reason they could not be read.
58
+ */
59
+ export declare function subnetsInRegion(region: string): Promise<{
60
+ readonly subnets: InventorySubnet[];
61
+ readonly failure?: string;
62
+ }>;
63
+ /**
64
+ * One VPC API subnet as an inventory resource.
65
+ *
66
+ * `properties.vpc_id` is what places it: `locationRank` reads the attribute's
67
+ * noun, so a subnet with this field lands inside its VPC by the same rule that
68
+ * puts anything else where it lives. The CIDR and gateway go along because a
69
+ * reader comparing subnets needs to see the ranges.
70
+ *
71
+ * @param subnet - one record from the API.
72
+ * @param region - the region it came from.
73
+ * @returns the resource, or `undefined` when it is missing the id every node
74
+ * needs.
75
+ */
76
+ export declare function asInventorySubnet(subnet: VpcSubnet, region: string): InventorySubnet | undefined;
77
+ export {};
78
+ //# sourceMappingURL=inventory-subnets.d.ts.map
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The absolute directory a caller's directory argument names.
3
+ *
4
+ * ## The problem this exists for
5
+ *
6
+ * Every tool in this plugin takes a directory. A model supplies it, and a model
7
+ * supplies what it just said: after `create_deployment({deployment:
8
+ * "huawei-topology"})` the next call passes `"huawei-topology"` again, because
9
+ * that is the name it has been using. A relative path is not wrong — it is how
10
+ * people talk about directories.
11
+ *
12
+ * What is wrong is leaving its meaning to Node. A relative path passed to
13
+ * `readFile` or `spawn` resolves against `process.cwd()`: the directory the
14
+ * host was launched from. That has nothing to do with the working directory the
15
+ * person chose for this session. Two tools then disagree — `write` saving to
16
+ * the session directory and `terraform_init` reading from the launch directory
17
+ * — and the symptom is a workspace nobody can find, which reads like a bug in
18
+ * whichever tool reported it first.
19
+ *
20
+ * So the anchor is explicit: the session's working directory, which is what
21
+ * every filesystem tool in the product uses and what a person means by "here".
22
+ *
23
+ * The rule is stated once here rather than per argument name, because it is a
24
+ * fact about directories, not about `deployment` in particular: `dest` is the
25
+ * same kind of value and had the same defect.
26
+ *
27
+ * ## Why there is no fallback
28
+ *
29
+ * When the host offers no session directory, a relative path has no correct
30
+ * meaning. Falling back to `process.cwd()` would restore the exact
31
+ * disagreement above, silently, for every call. The tools therefore ask for an
32
+ * absolute path in that case and say why — a caller can comply, and nobody
33
+ * writes somewhere unintended.
34
+ *
35
+ * An absolute path needs none of this: it already means one thing.
36
+ *
37
+ * @module @huaweidevtools/aishell-dsh-deploy/paths
38
+ */
39
+ import type { ToolContext } from './types.ts';
40
+ /**
41
+ * The absolute directory a directory argument names.
42
+ *
43
+ * @param given - the path the caller gave, relative or absolute.
44
+ * @param context - the call's context, carrying the session directory when the
45
+ * host provides one.
46
+ * @returns the absolute path.
47
+ * @throws when the path is relative and there is no session directory to anchor
48
+ * it — the caller gets a remedy, not a directory chosen for them.
49
+ */
50
+ export declare function anchorPath(given: string, context: ToolContext | undefined): string;
51
+ //# sourceMappingURL=paths.d.ts.map
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Where the account's projects are, by region.
3
+ *
4
+ * ## Why this is one module
5
+ *
6
+ * A region-scoped HuaweiCloud API puts a project id in the path, and the id is
7
+ * not the account id: one account has one project per region, and pairing a
8
+ * project with another region's host answers HTTP 400. Three callers need that
9
+ * mapping — the price quote, the catalogue lookup, and the subnet listing that
10
+ * completes an inventory — and three private copies of the same IAM call would
11
+ * be three places to keep in step.
12
+ *
13
+ * ## The endpoint is global
14
+ *
15
+ * `iam.myhuaweicloud.com` (no region prefix) answers with every project the
16
+ * account has, in every region, in one response. So one call serves a plan that
17
+ * spans several regions, and the result is worth keeping for the life of one
18
+ * tool call.
19
+ *
20
+ * @module @huaweidevtools/aishell-dsh-deploy/projects
21
+ */
22
+ import type { Credentials } from './credentials.ts';
23
+ /**
24
+ * Every project the account has, keyed by region name.
25
+ *
26
+ * @param credentials - the pair to sign with.
27
+ * @returns region name → project id.
28
+ * @throws when IAM cannot answer, with its own reason.
29
+ */
30
+ export declare function projectMap(credentials: Credentials): Promise<Map<string, string>>;
31
+ /**
32
+ * The project id for one region, or a message naming what the account does have.
33
+ *
34
+ * @param projects - the map from {@link projectMap}.
35
+ * @param region - the region a request is going to.
36
+ * @returns the project id.
37
+ * @throws when the account has no project there, listing the regions it does.
38
+ */
39
+ export declare function projectIn(projects: ReadonlyMap<string, string>, region: string): string;
40
+ //# sourceMappingURL=projects.d.ts.map