@n8n-as-code/n8nac 2.1.3-next.151 → 2.1.4

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/CHANGELOG.md +14 -0
  2. package/index.ts +9 -8
  3. package/package.json +2 -2
  4. package/skills/n8n-architect/SKILL.md +92 -120
  5. package/src/workspace.ts +21 -10
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # @n8n-as-code/n8nac
2
2
 
3
+ ## [2.1.4](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2.1.3...@n8n-as-code/n8nac@v2.1.4) (2026-06-05)
4
+
5
+ ### Bug Fixes
6
+
7
+ * address v4 workspace review feedback ([d111a7f](https://github.com/EtienneLescot/n8n-as-code/commit/d111a7fcc31cbdc2a3309cf4979395ee8f179880))
8
+ * require v4 workspace environments ([6967d4d](https://github.com/EtienneLescot/n8n-as-code/commit/6967d4d0ecbaa4d18fe0077f42531b215f574d5e))
9
+
10
+ ## [2.1.3](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2.1.2...@n8n-as-code/n8nac@v2.1.3) (2026-05-21)
11
+
12
+ ### Dependencies
13
+
14
+ * The following workspace dependencies were updated
15
+ * @n8n-as-code/telemetry bumped from 2.0.0 to 2.0.1
16
+
3
17
  ## [2.1.2](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2.1.1...@n8n-as-code/n8nac@v2.1.2) (2026-05-13)
4
18
 
5
19
  ### Documentation
package/index.ts CHANGED
@@ -26,9 +26,10 @@ Supported facade runtime modes:
26
26
  ${SETUP_MODE_CONTEXT}
27
27
 
28
28
  For agent-driven flows, use the installed \`n8n-manager\` and \`n8n-architect\`
29
- skills and their documented shell commands. Instance/auth/project management
30
- belongs to \`n8n-manager\`; context-root overrides and workflow sync belong
31
- to \`n8nac workspace\` and the n8n-as-code skills.
29
+ skills and their documented shell commands. Local managed runtime lifecycle
30
+ belongs to \`n8n-manager\`; environment/project/auth/workflowsPath management
31
+ uses V4 \`n8nac env\` commands such as \`env add\`, \`env update\`, and
32
+ \`env auth set\`, and workflow sync uses the n8n-as-code skills.
32
33
  `;
33
34
 
34
35
  function buildStatusHeader(workspaceDir: string): string {
@@ -39,13 +40,13 @@ function buildStatusHeader(workspaceDir: string): string {
39
40
  "**The context root is initialized. Do NOT infer effective n8n config from this prompt.**",
40
41
  "",
41
42
  `- Context root: \`${workspaceDir}\``,
42
- `- Local overrides file: \`${join(workspaceDir, "n8nac-config.json")}\``,
43
+ `- Workspace environment file: \`${join(workspaceDir, "n8nac-config.json")}\``,
43
44
  `- Bootstrap file: \`${join(workspaceDir, "AGENTS.md")}\``,
44
45
  "",
45
- "Before n8n work, run `n8nac workspace status --json` from the context root and use the backend-resolved result.",
46
- cfg.activeInstanceId || cfg.projectId || cfg.projectName || cfg.syncFolder
47
- ? "The local overrides file exists, but n8n-manager plus n8nac backend resolution remains the only source of effective state."
48
- : "The local overrides file is present but incomplete.",
46
+ "Before n8n work, run `n8nac env status --json` from the context root and use the backend-resolved result.",
47
+ cfg.environmentId || cfg.workflowsPath
48
+ ? "The workspace environment file exists, but n8nac backend resolution remains the only source of effective state."
49
+ : "The workspace environment file is present but incomplete.",
49
50
  ].join("\n");
50
51
  }
51
52
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n8n-as-code/n8nac",
3
- "version": "2.1.3-next.151",
3
+ "version": "2.1.4",
4
4
  "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
5
5
  "keywords": [
6
6
  "n8n",
@@ -24,7 +24,7 @@
24
24
  "typecheck": "tsc --noEmit"
25
25
  },
26
26
  "dependencies": {
27
- "@n8n-as-code/telemetry": "2.0.1-next.151",
27
+ "@n8n-as-code/telemetry": "2.0.1",
28
28
  "@n8n-as-code/workflow-core": "2.0.0"
29
29
  },
30
30
  "devDependencies": {
package/skills/n8n-architect/SKILL.md CHANGED
@@ -5,23 +5,23 @@ description: Use when the user explicitly wants to create, edit, validate, sync,
5
5
 
6
6
  # n8n Architect
7
7
 
8
- Use this skill for all n8n-as-code work: workspace readiness, migration, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.
8
+ Use this skill for all n8n-as-code work: workspace readiness, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.
9
9
 
10
- Use `npx --yes n8nac@next` as the primary interface. Use `npx --yes @n8n-as-code/n8n-manager@next` only for local managed runtime lifecycle, tunnels, and workflow presentation commands that are explicitly exposed by n8n-manager.
10
+ Use `npx --yes n8nac` as the primary interface. Use `npx --yes @n8n-as-code/n8n-manager` only for local managed runtime lifecycle, tunnels, and workflow presentation commands that are explicitly exposed by n8n-manager.
11
11
 
12
12
  ## Context Root Protocol
13
13
 
14
14
  - Treat the current context root as the directory containing `n8nac-config.json`, `AGENTS.md`, `.agents/skills`, and the configured `workflowsPath`.
15
15
  - Generated context root hint: not embedded. Use the shell launch directory or the workspace path explicitly given by the user.
16
- - Before any n8n work, first run `npx --yes n8nac@next update-ai` from the context root, then read `AGENTS.md`. `update-ai` is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
16
+ - Before any n8n work, first run `npx --yes n8nac update-ai` from the context root, then read `AGENTS.md`. `update-ai` is designed to create or refresh the n8n-as-code block without destroying existing user or agent instructions.
17
17
  - Use the exact `n8nac command` and `n8n-manager command` listed in `AGENTS.md`. Those context-root commands override the portable examples in this skill.
18
- - Run every `npx --yes n8nac@next env ...`, `npx --yes n8nac@next workspace ...`, `npx --yes n8nac@next list`, `pull`, `push`, `validate`, `test`, and `update-ai` command from the context root unless the user explicitly gives another context root.
18
+ - Run every `npx --yes n8nac env ...`, `npx --yes n8nac workspace ...`, `npx --yes n8nac list`, `pull`, `push`, `validate`, `test`, and `update-ai` command from the context root unless the user explicitly gives another context root.
19
19
  - `AGENTS.md` is bootstrap context only, not a source of configuration truth.
20
20
  - Do not infer environment, project, or `workflowsPath` from `AGENTS.md`.
21
21
  - Before n8n work, resolve the effective context from the backend:
22
22
 
23
23
  ```bash
24
- npx --yes n8nac@next env status --json
24
+ npx --yes n8nac env status --json
25
25
  ```
26
26
 
27
27
  - Use the returned `workflowsPath` for workflow files. It is the configured workflow directory for the active environment.
@@ -30,110 +30,82 @@ npx --yes n8nac@next env status --json
30
30
 
31
31
  ## Workspace Readiness
32
32
 
33
- Use the unified migration preflight before resolving the effective environment. The dry-run is safe and reports whether any workspace migration is required:
33
+ Resolve the effective environment through the backend before workflow work:
34
34
 
35
35
  ```bash
36
- npx --yes n8nac@next workspace migrate --json
37
- npx --yes n8nac@next env status --json
36
+ npx --yes n8nac env status --json
38
37
  ```
39
38
 
40
- - Treat `workspace migrate --json` as the source of migration need.
41
- - Treat `env status --json` as the source of effective workspace readiness only after migration is not required or has been applied.
39
+ - Treat `env status --json` as the source of effective workspace readiness.
42
40
  - Do not infer readiness from raw files, generated agent docs, or directory names.
43
- - If migration is required, do not edit config files by hand or continue with environment/workflow work until it has been applied or explicitly deferred by the user.
44
-
45
- ## Migration
46
-
47
- Migration is one user-facing command. Do not reason about internal migration phases directly; summarize the report `operations` array when explaining what will change.
48
-
49
- 1. Run the dry-run first:
50
-
51
- ```bash
52
- npx --yes n8nac@next workspace migrate --json
53
- ```
54
-
55
- 2. If the dry-run reports `status: "dry-run"`, `required: true`, or otherwise indicates pending changes, stop and ask once before applying it. Do not run `workspace migrate --write` unless the user already directly requested applying migration.
56
- 3. After confirmation, apply migration and re-check readiness:
57
-
58
- ```bash
59
- npx --yes n8nac@next workspace migrate --write
60
- npx --yes n8nac@next workspace migrate --json
61
- npx --yes n8nac@next env status --json
62
- ```
63
-
64
- - Do not run `workspace migrate --write` without explicit confirmation unless the user already directly requested applying migration.
65
- - When reporting a dry-run, summarize the unified `operations` list and ask for exactly one confirmation for `npx --yes n8nac@next workspace migrate --write`.
66
- - Do not ask separately for different operation types. `npx --yes n8nac@next workspace migrate --write` applies the required migration as one operation.
67
- - Do not run environment, workflow, or setup commands while `workspace migrate --json` still reports migration required.
41
+ - If `env status --json` fails because the workspace is not configured, use `env add`, `env auth set`, and `env use` to create or select a V4 workspace environment.
68
42
  - Managed local instances remain machine-global runtime resources.
69
- - Workspace environments remain workspace-scoped and are managed through `npx --yes n8nac@next env ...`.
43
+ - Workspace environments remain workspace-scoped and are managed through `npx --yes n8nac env ...`.
70
44
 
71
45
  ## Bootstrap Order
72
46
 
73
47
  1. `cd` to the context root.
74
- 2. Run `npx --yes n8nac@next update-ai`, then read `AGENTS.md`.
75
- 3. Run `npx --yes n8nac@next workspace migrate --json`.
76
- 4. If migration is required, stop and ask for confirmation before `npx --yes n8nac@next workspace migrate --write` unless the user already requested applying migration.
77
- 5. Run `npx --yes n8nac@next env status --json` after migration is not required or has been applied.
78
- 6. If the context root is not ready, inspect managed local instances with `npx --yes @n8n-as-code/n8n-manager@next instance list`.
79
- 7. Reuse an existing environment or managed local instance when suitable.
80
- 8. If no suitable environment exists, stop and ask the user whether they want to connect a remote n8n URL or create/reuse a managed local n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel.
81
- 9. Ask for host/API key only for an explicitly remote n8n environment.
82
- 10. Configure the environment with:
48
+ 2. Run `npx --yes n8nac update-ai`, then read `AGENTS.md`.
49
+ 3. Run `npx --yes n8nac env status --json`.
50
+ 4. If the context root is not ready, inspect managed local instances with `npx --yes @n8n-as-code/n8n-manager instance list`.
51
+ 5. Reuse an existing environment or managed local instance when suitable.
52
+ 6. If no suitable environment exists, stop and ask the user whether they want to connect a remote n8n URL or create/reuse a managed local n8n instance. Do not create infrastructure by default. If the user chooses a managed local instance, ask separately whether they want a public tunnel.
53
+ 7. Ask for host/API key only for an explicitly remote n8n environment.
54
+ 8. Configure the environment with:
83
55
 
84
56
  ```bash
85
- npx --yes n8nac@next env add <name> --base-url <url> --workflows-path workflows/<name>
86
- npx --yes n8nac@next env auth set <name> --api-key-stdin
87
- npx --yes n8nac@next env use <name>
57
+ npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
58
+ npx --yes n8nac env auth set <name> --api-key-stdin
59
+ npx --yes n8nac env use <name>
88
60
  ```
89
61
 
90
62
  For a managed local instance:
91
63
 
92
64
  ```bash
93
- npx --yes n8nac@next env add Local --managed-instance <id> --workflows-path workflows/local
94
- npx --yes n8nac@next env use Local
65
+ npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
66
+ npx --yes n8nac env use Local
95
67
  ```
96
68
 
97
- 11. Run `npx --yes n8nac@next update-ai` after changing environments when the facade does not do it automatically.
69
+ 9. Run `npx --yes n8nac update-ai` after changing environments when the facade does not do it automatically.
98
70
 
99
71
  ## Environments
100
72
 
101
- Use `npx --yes n8nac@next env ...` for workspace environments, remote URLs, active environment, API-key binding, projects, and workflow paths.
73
+ Use `npx --yes n8nac env ...` for workspace environments, remote URLs, active environment, API-key binding, projects, and workflow paths.
102
74
 
103
75
  ```bash
104
- npx --yes n8nac@next env status --json
105
- npx --yes n8nac@next env list
106
- npx --yes n8nac@next env add <name> --base-url <url> --workflows-path workflows/<name>
107
- npx --yes n8nac@next env auth set <name> --api-key-stdin
108
- npx --yes n8nac@next env use <name>
76
+ npx --yes n8nac env status --json
77
+ npx --yes n8nac env list
78
+ npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
79
+ npx --yes n8nac env auth set <name> --api-key-stdin
80
+ npx --yes n8nac env use <name>
109
81
  ```
110
82
 
111
83
  - Prefer `--api-key-stdin` for API keys.
112
84
  - Do not pass secrets inline in shell arguments.
113
85
  - Do not ask for host/API key when the user wants a managed local Docker instance.
114
86
  - Do not print API keys or credential secret values back to the user.
115
- - If a command or flag is unfamiliar, run `npx --yes n8nac@next env --help` or `npx --yes n8nac@next env <subcommand> --help`.
87
+ - If a command or flag is unfamiliar, run `npx --yes n8nac env --help` or `npx --yes n8nac env <subcommand> --help`.
116
88
 
117
- Attach a managed local instance to the workspace with `npx --yes n8nac@next env ...`:
89
+ Attach a managed local instance to the workspace with `npx --yes n8nac env ...`:
118
90
 
119
91
  ```bash
120
- npx --yes n8nac@next env add Local --managed-instance <id> --workflows-path workflows/local
121
- npx --yes n8nac@next env use Local
92
+ npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
93
+ npx --yes n8nac env use Local
122
94
  ```
123
95
 
124
96
  ## Managed Local Runtime
125
97
 
126
- Use `npx --yes @n8n-as-code/n8n-manager@next` only for local managed instance lifecycle, tunnels, and workflow presentation commands that are part of the local runtime layer.
98
+ Use `npx --yes @n8n-as-code/n8n-manager` only for local managed instance lifecycle, tunnels, and workflow presentation commands that are part of the local runtime layer.
127
99
 
128
100
  Inspect existing managed instances before changing local machine state:
129
101
 
130
102
  ```bash
131
- npx --yes @n8n-as-code/n8n-manager@next instance list
132
- npx --yes @n8n-as-code/n8n-manager@next instance --help
133
- npx --yes @n8n-as-code/n8n-manager@next config get
103
+ npx --yes @n8n-as-code/n8n-manager instance list
104
+ npx --yes @n8n-as-code/n8n-manager instance --help
105
+ npx --yes @n8n-as-code/n8n-manager config get
134
106
  ```
135
107
 
136
- Do not invent n8n-manager subcommands. Use `npx --yes @n8n-as-code/n8n-manager@next <subcommand> --help` when unsure.
108
+ Do not invent n8n-manager subcommands. Use `npx --yes @n8n-as-code/n8n-manager <subcommand> --help` when unsure.
137
109
 
138
110
  When the context root is not configured and no suitable existing instance is available, stop and ask the user to choose. Do not create infrastructure by default.
139
111
 
@@ -141,7 +113,7 @@ Present these choices clearly:
141
113
 
142
114
  - use an existing managed local instance if one is available;
143
115
  - create a new managed local n8n instance;
144
- - configure a remote n8n URL as a workspace environment through `npx --yes n8nac@next env`.
116
+ - configure a remote n8n URL as a workspace environment through `npx --yes n8nac env`.
145
117
 
146
118
  If the user chooses a managed local Docker instance, ask the tunnel question separately:
147
119
 
@@ -155,27 +127,27 @@ Only run these commands after the user has explicitly chosen the corresponding o
155
127
  Managed local instance without public tunnel:
156
128
 
157
129
  ```bash
158
- npx --yes @n8n-as-code/n8n-manager@next instance create
159
- npx --yes @n8n-as-code/n8n-manager@next instance start <id>
160
- npx --yes @n8n-as-code/n8n-manager@next instance list
130
+ npx --yes @n8n-as-code/n8n-manager instance create
131
+ npx --yes @n8n-as-code/n8n-manager instance start <id>
132
+ npx --yes @n8n-as-code/n8n-manager instance list
161
133
  ```
162
134
 
163
135
  Managed local instance with public tunnel:
164
136
 
165
137
  ```bash
166
- npx --yes @n8n-as-code/n8n-manager@next instance create
167
- npx --yes @n8n-as-code/n8n-manager@next instance start <id>
168
- npx --yes @n8n-as-code/n8n-manager@next tunnel start <id>
138
+ npx --yes @n8n-as-code/n8n-manager instance create
139
+ npx --yes @n8n-as-code/n8n-manager instance start <id>
140
+ npx --yes @n8n-as-code/n8n-manager tunnel start <id>
169
141
  ```
170
142
 
171
143
  Instance and tunnel operations are per managed local instance:
172
144
 
173
145
  ```bash
174
- npx --yes @n8n-as-code/n8n-manager@next instance start <id>
175
- npx --yes @n8n-as-code/n8n-manager@next instance stop <id>
176
- npx --yes @n8n-as-code/n8n-manager@next instance remove <id>
177
- npx --yes @n8n-as-code/n8n-manager@next tunnel start <id>
178
- npx --yes @n8n-as-code/n8n-manager@next tunnel stop <id>
146
+ npx --yes @n8n-as-code/n8n-manager instance start <id>
147
+ npx --yes @n8n-as-code/n8n-manager instance stop <id>
148
+ npx --yes @n8n-as-code/n8n-manager instance remove <id>
149
+ npx --yes @n8n-as-code/n8n-manager tunnel start <id>
150
+ npx --yes @n8n-as-code/n8n-manager tunnel stop <id>
179
151
  ```
180
152
 
181
153
  - Do not delete local instance data unless the user explicitly asks for destructive deletion.
@@ -189,13 +161,13 @@ npx --yes @n8n-as-code/n8n-manager@next tunnel stop <id>
189
161
  - Use `list` to inspect workflow IDs, file paths, and sync status.
190
162
 
191
163
  ```bash
192
- npx --yes n8nac@next list
193
- npx --yes n8nac@next pull <workflowId>
194
- npx --yes n8nac@next push <path-to-workflow.workflow.ts> --verify
164
+ npx --yes n8nac list
165
+ npx --yes n8nac pull <workflowId>
166
+ npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
195
167
  ```
196
168
 
197
169
  - `push` requires the full workflow file path, either absolute or context-root-relative. Do not pass a bare filename.
198
- - For a new workflow, create the file inside the `workflowsPath` returned by `env status --json`, then confirm it with `npx --yes n8nac@next list --local`.
170
+ - For a new workflow, create the file inside the `workflowsPath` returned by `env status --json`, then confirm it with `npx --yes n8nac list --local`.
199
171
  - If push/pull reports a conflict, use explicit resolution commands. Do not overwrite remote changes blindly.
200
172
  - `pull` and conflict resolution operate on a single workflow ID.
201
173
  - `list` is the lightweight command that covers all workflows at once.
@@ -206,8 +178,8 @@ npx --yes n8nac@next push <path-to-workflow.workflow.ts> --verify
206
178
  If push or pull reports a conflict, stop and inspect the conflict. Use explicit resolution commands only after choosing the intended direction:
207
179
 
208
180
  ```bash
209
- npx --yes n8nac@next resolve <workflowId> --mode keep-current
210
- npx --yes n8nac@next resolve <workflowId> --mode keep-incoming
181
+ npx --yes n8nac resolve <workflowId> --mode keep-current
182
+ npx --yes n8nac resolve <workflowId> --mode keep-incoming
211
183
  ```
212
184
 
213
185
  - `keep-current` force-pushes the local version.
@@ -219,10 +191,10 @@ npx --yes n8nac@next resolve <workflowId> --mode keep-incoming
219
191
  Never guess n8n node parameters.
220
192
 
221
193
  ```bash
222
- npx --yes n8nac@next skills examples search "<workflow pattern>"
223
- npx --yes n8nac@next skills search "<node or capability>"
224
- npx --yes n8nac@next skills node-info <nodeName>
225
- npx --yes n8nac@next skills validate <workflow.workflow.ts>
194
+ npx --yes n8nac skills examples search "<workflow pattern>"
195
+ npx --yes n8nac skills search "<node or capability>"
196
+ npx --yes n8nac skills node-info <nodeName>
197
+ npx --yes n8nac skills validate <workflow.workflow.ts>
226
198
  ```
227
199
 
228
200
  - Use exact node `type` and valid `typeVersion` values from `node-info`.
@@ -237,19 +209,19 @@ npx --yes n8nac@next skills validate <workflow.workflow.ts>
237
209
  Use these commands instead of guessing:
238
210
 
239
211
  ```bash
240
- npx --yes n8nac@next skills search "<node or capability>"
241
- npx --yes n8nac@next skills node-info <nodeName>
242
- npx --yes n8nac@next skills node-schema <nodeName>
243
- npx --yes n8nac@next skills docs "<topic>"
244
- npx --yes n8nac@next skills guides "<topic>"
245
- npx --yes n8nac@next skills examples search "<workflow pattern>"
246
- npx --yes n8nac@next skills examples info <id>
247
- npx --yes n8nac@next skills examples download <id>
212
+ npx --yes n8nac skills search "<node or capability>"
213
+ npx --yes n8nac skills node-info <nodeName>
214
+ npx --yes n8nac skills node-schema <nodeName>
215
+ npx --yes n8nac skills docs "<topic>"
216
+ npx --yes n8nac skills guides "<topic>"
217
+ npx --yes n8nac skills examples search "<workflow pattern>"
218
+ npx --yes n8nac skills examples info <id>
219
+ npx --yes n8nac skills examples download <id>
248
220
  ```
249
221
 
250
222
  - Start with `examples search` when the user asks for a common automation pattern.
251
223
  - Use examples to learn patterns, not as authority over current node schemas.
252
- - If a command or flag is unfamiliar, run `npx --yes n8nac@next <subcommand> --help`; do not invent flags.
224
+ - If a command or flag is unfamiliar, run `npx --yes n8nac <subcommand> --help`; do not invent flags.
253
225
 
254
226
  ## Workflow Authoring Rules
255
227
 
@@ -389,15 +361,15 @@ defineRouting() {
389
361
  After pushing:
390
362
 
391
363
  ```bash
392
- npx --yes n8nac@next verify <workflowId>
393
- npx --yes n8nac@next test-plan <workflowId> --json
364
+ npx --yes n8nac verify <workflowId>
365
+ npx --yes n8nac test-plan <workflowId> --json
394
366
  ```
395
367
 
396
368
  For webhook, chat, or form workflows, prefer the production test sequence:
397
369
 
398
370
  ```bash
399
- npx --yes n8nac@next workflow activate <workflowId>
400
- npx --yes n8nac@next test <workflowId> --prod
371
+ npx --yes n8nac workflow activate <workflowId>
372
+ npx --yes n8nac test <workflowId> --prod
401
373
  ```
402
374
 
403
375
  - Class A configuration gaps require user/config action, not workflow rewrites.
@@ -407,7 +379,7 @@ npx --yes n8nac@next test <workflowId> --prod
407
379
 
408
380
  ## Workflow Presentation Contract
409
381
 
410
- `npx --yes n8nac@next workflow present` is the standard way to show a workflow to the user. It is v4-environment aware and part of the workflow authoring loop.
382
+ `npx --yes n8nac workflow present` is the standard way to show a workflow to the user. It is v4-environment aware and part of the workflow authoring loop.
411
383
 
412
384
  Run it whenever one of these is true:
413
385
 
@@ -417,7 +389,7 @@ Run it whenever one of these is true:
417
389
  - the user asks to show, open, present, display, or give the URL/link for a workflow.
418
390
 
419
391
  ```bash
420
- npx --yes n8nac@next workflow present <workflowId> --json
392
+ npx --yes n8nac workflow present <workflowId> --json
421
393
  ```
422
394
 
423
395
  Rules:
@@ -425,8 +397,8 @@ Rules:
425
397
  - Do not manually construct n8n workflow URLs.
426
398
  - Do not return an internal local n8n URL when a presentation URL is available.
427
399
  - Use the `url` returned by `workflow present --json` as the user-facing URL.
428
- - If you do not know the workflow ID, run `npx --yes n8nac@next list` first and select the matching workflow.
429
- - Do not call `npx --yes @n8n-as-code/n8n-manager@next presentWorkflowResult`; it is a legacy runtime command and is not workspace-environment aware.
400
+ - If you do not know the workflow ID, run `npx --yes n8nac list` first and select the matching workflow.
401
+ - Do not call `npx --yes @n8n-as-code/n8n-manager presentWorkflowResult`; it is a legacy runtime command and is not workspace-environment aware.
430
402
  - If `workflow present` fails, report the backend diagnostic and then provide the best direct n8n URL only as a fallback.
431
403
  - Do this before the final response when the task created, changed, pushed, ran, or explicitly asks to show a workflow.
432
404
 
@@ -440,18 +412,18 @@ For webhook, chat, or form workflows:
440
412
  4. Test with `--prod` by default.
441
413
 
442
414
  ```bash
443
- npx --yes n8nac@next push <path-to-workflow.workflow.ts> --verify
444
- npx --yes n8nac@next test-plan <workflowId> --json
445
- npx --yes n8nac@next workflow activate <workflowId>
446
- npx --yes n8nac@next test <workflowId> --prod
415
+ npx --yes n8nac push <path-to-workflow.workflow.ts> --verify
416
+ npx --yes n8nac test-plan <workflowId> --json
417
+ npx --yes n8nac workflow activate <workflowId>
418
+ npx --yes n8nac test <workflowId> --prod
447
419
  ```
448
420
 
449
- Use bare `npx --yes n8nac@next test <workflowId>` only when a test URL was intentionally armed in the n8n editor.
421
+ Use bare `npx --yes n8nac test <workflowId>` only when a test URL was intentionally armed in the n8n editor.
450
422
 
451
423
  For GET/HEAD webhooks that read from `$json.query`, prefer:
452
424
 
453
425
  ```bash
454
- npx --yes n8nac@next test <workflowId> --query '{"key":"value"}' --prod
426
+ npx --yes n8nac test <workflowId> --query '{"key":"value"}' --prod
455
427
  ```
456
428
 
457
429
  ## Execution Debugging
@@ -459,8 +431,8 @@ npx --yes n8nac@next test <workflowId> --query '{"key":"value"}' --prod
459
431
  If a webhook returns success but the workflow behavior is wrong, inspect executions instead of guessing:
460
432
 
461
433
  ```bash
462
- npx --yes n8nac@next execution list --workflow-id <workflowId> --limit 5 --json
463
- npx --yes n8nac@next execution get <executionId> --include-data --json
434
+ npx --yes n8nac execution list --workflow-id <workflowId> --limit 5 --json
435
+ npx --yes n8nac execution get <executionId> --include-data --json
464
436
  ```
465
437
 
466
438
  - A successful HTTP trigger only means n8n accepted the request.
@@ -472,11 +444,11 @@ npx --yes n8nac@next execution get <executionId> --include-data --json
472
444
  When a workflow is blocked by missing credentials, resolve the credential gap without rewriting unrelated workflow logic.
473
445
 
474
446
  ```bash
475
- npx --yes n8nac@next workflow credential-required <workflowId> --json
476
- npx --yes n8nac@next credential schema <type>
477
- npx --yes n8nac@next credential list --json
478
- npx --yes n8nac@next credential create --type <type> --name <name> --file cred.json --json
479
- npx --yes n8nac@next workflow activate <workflowId>
447
+ npx --yes n8nac workflow credential-required <workflowId> --json
448
+ npx --yes n8nac credential schema <type>
449
+ npx --yes n8nac credential list --json
450
+ npx --yes n8nac credential create --type <type> --name <name> --file cred.json --json
451
+ npx --yes n8nac workflow activate <workflowId>
480
452
  ```
481
453
 
482
454
  - `workflow credential-required` exits non-zero when at least one credential is missing. Treat that as a signal to act, not as a workflow-code failure.
@@ -500,12 +472,12 @@ For most workflow tasks:
500
472
  8. Push with `--verify`.
501
473
  9. Test if the workflow is HTTP-triggered.
502
474
  10. Inspect executions when behavior is unclear.
503
- 11. Present the final workflow link with `npx --yes n8nac@next workflow present <workflowId> --json`.
475
+ 11. Present the final workflow link with `npx --yes n8nac workflow present <workflowId> --json`.
504
476
 
505
477
  ## Response Discipline
506
478
 
507
479
  - Explain concrete actions and command results, not generic capability.
508
- - When the user asks for an URL or visual inspection of a workflow, run `npx --yes n8nac@next workflow present <workflowId> --json` instead of composing a URL manually.
480
+ - When the user asks for an URL or visual inspection of a workflow, run `npx --yes n8nac workflow present <workflowId> --json` instead of composing a URL manually.
509
481
  - If setup is missing, use `n8nac env ...` for workspace environments and `n8n-manager` only for managed local instances.
510
482
  - Do not ask for host/API key unless the user chooses a remote n8n environment.
511
483
  - Do not tell the user to run setup commands when you can run non-interactive commands yourself.
package/src/workspace.ts CHANGED
@@ -3,16 +3,18 @@ import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
 
5
5
  export type WorkspaceBinding = {
6
+ activeEnvironmentId?: string;
7
+ environmentId?: string;
8
+ environmentName?: string;
9
+ workflowsPath?: string;
6
10
  projectId?: string;
7
11
  projectName?: string;
8
- syncFolder?: string;
9
- activeInstanceId?: string;
10
12
  };
11
13
 
12
14
  /**
13
- * Fixed context-root directory for V1.
15
+ * Fixed context-root directory for n8n-as-code.
14
16
  * All n8nac context files (n8nac-config.json, AGENTS.md, .agents/skills, workflows/) live here.
15
- * n8n instances and credentials are stored globally by n8n-manager.
17
+ * Runtime access is resolved through V4 workspace environments.
16
18
  */
17
19
  export function getWorkspaceDir(): string {
18
20
  return join(homedir(), ".openclaw", "n8nac");
@@ -31,12 +33,21 @@ export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
31
33
  try {
32
34
  const raw = readFileSync(configPath, "utf-8");
33
35
  const config = JSON.parse(raw) as Record<string, unknown>;
36
+ if (config.version !== 4) return {};
37
+ const environments = Array.isArray(config.environments) ? config.environments as Array<Record<string, unknown>> : [];
38
+ const activeEnvironmentId = readString(config.activeEnvironmentId);
39
+ const environment = activeEnvironmentId
40
+ ? environments.find((item) => readString(item.id) === activeEnvironmentId)
41
+ : environments[0];
42
+ if (!environment) return { activeEnvironmentId: activeEnvironmentId || undefined };
34
43
 
35
44
  return {
36
- projectId: readString(config.projectId) || undefined,
37
- projectName: readString(config.projectName) || undefined,
38
- syncFolder: readString(config.syncFolder) || undefined,
39
- activeInstanceId: readString(config.activeInstanceId) || undefined,
45
+ activeEnvironmentId: activeEnvironmentId || undefined,
46
+ environmentId: readString(environment.id) || undefined,
47
+ environmentName: readString(environment.name) || undefined,
48
+ workflowsPath: readString(environment.workflowsPath) || undefined,
49
+ projectId: readString(environment.projectId) || undefined,
50
+ projectName: readString(environment.projectName) || undefined,
40
51
  };
41
52
  } catch {
42
53
  return {};
@@ -45,9 +56,9 @@ export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
45
56
 
46
57
  /**
47
58
  * Returns true when n8nac has been initialized in the given directory,
48
- * meaning the config exists and contains a selected project + sync folder.
59
+ * meaning the config exists and contains an active V4 environment with workflowsPath.
49
60
  */
50
61
  export function isWorkspaceInitialized(workspaceDir: string): boolean {
51
62
  const binding = readWorkspaceBinding(workspaceDir);
52
- return Boolean(binding.projectId && binding.projectName && binding.syncFolder);
63
+ return Boolean(binding.environmentId && binding.workflowsPath);
53
64
  }