awscfn 1.1.1 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +80 -40
  2. package/bin/awscfn +1 -0
  3. package/dist/lib/cfn/executeChangeSet.js +1 -1
  4. package/dist/lib/cfn/executeChangeSet.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -9,15 +9,51 @@
9
9
  [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
10
10
  [![AutoRel](https://img.shields.io/badge/%F0%9F%9A%80%20AutoRel-2D4DDE)](https://github.com/mhweiner/autorel)
11
11
 
12
- CLI and TypeScript SDK for managing AWS CloudFormation stacks.
12
+ Deploy CloudFormation stacks without the usual suffering.
13
13
 
14
14
  ## Why awscfn?
15
15
 
16
- - **Simple YAML parameters** — No more wrestling with verbose JSON. Just clean, readable YAML files.
17
- - **See what's happening** — Real-time event streaming in your terminal. No refreshing the console, no juggling `aws cloudformation create-stack` and `describe-stack-events` in another window.
18
- - **Errors that make sense** — When deploys fail, you get the actual error message from CloudFormation, not a cryptic timeout.
19
- - **CI/CD friendly** — Works great in GitHub Actions with auto-detected CI mode.
20
- - **CLI & SDK** — Use from command line or import directly in Node.js/TypeScript projects.
16
+ If you've deployed CloudFormation stacks, you know the pain:
17
+
18
+ - You run `aws cloudformation create-stack` and get... nothing. Is it working? Who knows.
19
+ - You open the AWS console, hit refresh, scroll through events, trying to find the one that matters.
20
+ - It fails. The error says "Resource creation cancelled." The *actual* reason is buried somewhere in the event log.
21
+ - The stack is stuck in `ROLLBACK_COMPLETE`. Now you have to delete it manually before you can try again.
22
+ - Your CI job times out or exits 0 even though the deploy failed.
23
+ - You write a parameter file and remember: oh right, CloudFormation wants *that* JSON format.
24
+
25
+ **awscfn fixes this.**
26
+
27
+ - **Watch deploys happen** — Stack events stream to your terminal in real time. No refreshing. No second window.
28
+ - **See why it failed** — When a deploy fails, you get the actual failure reason, not "Resource creation cancelled."
29
+ - **Recover automatically** — Stuck in `ROLLBACK_COMPLETE`? awscfn detects it and re-creates the stack for you.
30
+ - **YAML params** — Simple YAML parameter files. No more verbose JSON.
31
+ - **CI that works** — Auto-detects CI environments. Exits non-zero when deploys fail. Compact output mode.
32
+ - **CLI + TypeScript SDK** — Use from the command line or import directly into Node.js/TypeScript projects.
33
+
34
+ It's not a CDK. It's not a framework. It's just a better way to deploy raw CloudFormation.
35
+
36
+ ## Installation
37
+
38
+ **Global install** (recommended for CLI use):
39
+
40
+ ```bash
41
+ npm i -g awscfn
42
+ ```
43
+
44
+ Then run commands directly: `awscfn create-stack ...`
45
+
46
+ **Project dependency** (for SDK/library use):
47
+
48
+ ```bash
49
+ npm i awscfn
50
+ ```
51
+
52
+ **npx** (no install):
53
+
54
+ ```bash
55
+ npx awscfn create-stack ...
56
+ ```
21
57
 
22
58
  ## CLI commands
23
59
 
@@ -25,13 +61,15 @@ CLI and TypeScript SDK for managing AWS CloudFormation stacks.
25
61
 
26
62
  ### Global Options
27
63
 
28
- | Flag | Short | Description |
29
- |------|-------|-------------|
30
- | `--ci` | — | CI mode (compact output). Auto-detected when `CI=true` or `GITHUB_ACTIONS=true`. Colors stay on in CI (e.g. GitHub Actions supports ANSI). |
31
- | `--no-color` | `-N` | Disable colored output |
32
- | `--verbose` | `-V` | Show full error details (e.g. `err.data` JSON) on failure |
33
- | `--help` | `-h` | Show help |
34
- | `--version` | `-v` | Show version |
64
+ | Flag | Description |
65
+ |------|-------------|
66
+ | `--ci`, `-C` | CI mode (compact output). Auto-detected when `CI=true` or `GITHUB_ACTIONS=true`. |
67
+ | `--no-color`, `-N` | Disable colored output |
68
+ | `--verbose`, `-V` | Show full error details on failure |
69
+ | `--help`, `-h` | Show help |
70
+ | `--version`, `-v` | Show version |
71
+
72
+ Run `awscfn --help` or `awscfn <command> --help` for full CLI usage.
35
73
 
36
74
  ### Shell Completion
37
75
 
@@ -63,34 +101,32 @@ When a failure occurs, the error message includes the actual reason from CloudFo
63
101
  List all CloudFormation stacks in the current region (name, status, creation date).
64
102
 
65
103
  ```bash
66
- npx awscfn list-stacks
104
+ awscfn list-stacks
67
105
  ```
68
106
 
69
- No options. Output is a table of stack name, status, and creation date.
70
-
71
107
  ### 🚀 create-stack
72
108
 
73
109
  ```bash
74
- npx awscfn create-stack -n <STACK_NAME> -t <TEMPLATE_FILE> -p <PARAMS_FILE>
110
+ awscfn create-stack -n <STACK_NAME> -t <TEMPLATE_FILE> -p <PARAMS_FILE>
75
111
  ```
76
112
 
77
- | Flag | Short | Description |
78
- |------|-------|-------------|
79
- | `--name` | `-n` | Stack name |
80
- | `--template` | `-t` | CloudFormation template file |
81
- | `--params` | `-p` | Parameters file (YAML) |
113
+ | Flag | Description |
114
+ |------|-------------|
115
+ | `--name`, `-n` | Stack name |
116
+ | `--template`, `-t` | CloudFormation template file |
117
+ | `--params`, `-p` | Parameters file (YAML) |
82
118
 
83
119
  ### ⬆️ update-stack
84
120
 
85
121
  ```bash
86
- npx awscfn update-stack -n <STACK_NAME> -t <TEMPLATE_FILE> -p <PARAMS_FILE>
122
+ awscfn update-stack -n <STACK_NAME> -t <TEMPLATE_FILE> -p <PARAMS_FILE>
87
123
  ```
88
124
 
89
- | Flag | Short | Description |
90
- |------|-------|-------------|
91
- | `--name` | `-n` | Stack name |
92
- | `--template` | `-t` | CloudFormation template file |
93
- | `--params` | `-p` | Parameters file (YAML) |
125
+ | Flag | Description |
126
+ |------|-------------|
127
+ | `--name`, `-n` | Stack name |
128
+ | `--template`, `-t` | CloudFormation template file |
129
+ | `--params`, `-p` | Parameters file (YAML) |
94
130
 
95
131
  If there are no changes to apply, the command succeeds gracefully:
96
132
  ```
@@ -100,13 +136,13 @@ If there are no changes to apply, the command succeeds gracefully:
100
136
  ### ♻️ redeploy-stack
101
137
 
102
138
  ```bash
103
- npx awscfn redeploy-stack -n <STACK_NAME> -t <TEMPLATE_FILE>
139
+ awscfn redeploy-stack -n <STACK_NAME> -t <TEMPLATE_FILE>
104
140
  ```
105
141
 
106
- | Flag | Short | Description |
107
- |------|-------|-------------|
108
- | `--name` | `-n` | Stack name |
109
- | `--template` | `-t` | CloudFormation template file |
142
+ | Flag | Description |
143
+ |------|-------------|
144
+ | `--name`, `-n` | Stack name |
145
+ | `--template`, `-t` | CloudFormation template file |
110
146
 
111
147
  Redeploys using the existing stack's parameters. Useful for updating a stack with a new template without re-specifying params, or re-deploying after a failed create.
112
148
 
@@ -115,20 +151,20 @@ Redeploys using the existing stack's parameters. Useful for updating a stack wit
115
151
  Deletes a CloudFormation stack with a confirmation safeguard.
116
152
 
117
153
  ```bash
118
- npx awscfn delete-stack -n <STACK_NAME> -c <STACK_NAME>
154
+ awscfn delete-stack -n <STACK_NAME> -c <STACK_NAME>
119
155
  ```
120
156
 
121
- | Flag | Short | Description |
122
- |------|-------|-------------|
123
- | `--name` | `-n` | Stack name |
124
- | `--confirm` | `-c` | Repeat stack name to confirm |
157
+ | Flag | Description |
158
+ |------|-------------|
159
+ | `--name`, `-n` | Stack name |
160
+ | `--confirm`, `-c` | Repeat stack name to confirm |
125
161
 
126
- `-c` must match `-n` exactly to prevent accidental deletion.
162
+ `--confirm` must match `--name` exactly to prevent accidental deletion.
127
163
 
128
164
  **Example:**
129
165
 
130
166
  ```bash
131
- npx awscfn delete-stack -n my-app-prod -c my-app-prod
167
+ awscfn delete-stack -n my-app-prod -c my-app-prod
132
168
  ```
133
169
 
134
170
  If the stack doesn't exist, the command will exit with an error.
@@ -140,6 +176,10 @@ If the names don't match, the deletion will be aborted.
140
176
 
141
177
  > ⚠️ Requires AWS credentials to be configured in your shell or environment. [Start here](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) if you haven't already.
142
178
 
179
+ ### Nested stacks and IAM
180
+
181
+ Change sets request **`CAPABILITY_NAMED_IAM`** and **`CAPABILITY_AUTO_EXPAND`**, so stacks that define named IAM resources or **nested stacks** (including templates from [`aws cloudformation package`](https://docs.aws.amazon.com/cli/latest/reference/cloudformation/package.html)) work with **`create-stack`** / **`update-stack`** and the SDK `createStack` / `updateStack` helpers.
182
+
143
183
  ### 📋 `listStacks(): Promise<StackSummary[]>`
144
184
 
145
185
  Returns all CloudFormation stacks in the current region (paginated). Excludes deleted stacks (`DELETE_COMPLETE`, `DELETE_IN_PROGRESS`) via `StackStatusFilter`. Each item is an AWS SDK `StackSummary` (e.g. `StackName`, `StackStatus`, `CreationTime`).
package/bin/awscfn CHANGED
@@ -97,6 +97,7 @@ const confirmOpt = {
97
97
  yargs
98
98
  .option('ci', {
99
99
  type: 'boolean',
100
+ alias: 'C',
100
101
  description: 'CI mode (compact output). Auto-detected when CI=true or GITHUB_ACTIONS=true. Colors remain enabled in CI.',
101
102
  default: isCI,
102
103
  })
package/dist/lib/cfn/executeChangeSet.js CHANGED
@@ -30,7 +30,7 @@ async function createChangeSet(stackName, template, operation) {
30
30
  ChangeSetName: changeSetName,
31
31
  ChangeSetType: operation,
32
32
  Parameters: parameters,
33
- Capabilities: ['CAPABILITY_NAMED_IAM'],
33
+ Capabilities: ['CAPABILITY_NAMED_IAM', 'CAPABILITY_AUTO_EXPAND'],
34
34
  }));
35
35
  const cfg = (0, output_1.getOutputConfig)();
36
36
  const stopSpinner = cfg.ci ? null : (0, output_1.startSpinner)();
package/dist/lib/cfn/executeChangeSet.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"executeChangeSet.js","sourceRoot":"","sources":["../../../src/lib/cfn/executeChangeSet.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"executeChangeSet.js","sourceRoot":"","sources":["../../../src/lib/cfn/executeChangeSet.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "awscfn",
3
- "version": "1.1.1",
3
+ "version": "1.1.3",
4
4
  "description": "CLI and TypeScript SDK for managing AWS CloudFormation stacks with simple YAML parameters and real-time event streaming.",
5
5
  "type": "commonjs",
6
6
  "main": "./dist/index.js",