@n8n-as-code/n8nac 2.1.3 → 2.1.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @n8n-as-code/n8nac
 
+## [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)
+
+### Bug Fixes
+
+* address v4 workspace review feedback ([d111a7f](https://github.com/EtienneLescot/n8n-as-code/commit/d111a7fcc31cbdc2a3309cf4979395ee8f179880))
+* require v4 workspace environments ([6967d4d](https://github.com/EtienneLescot/n8n-as-code/commit/6967d4d0ecbaa4d18fe0077f42531b215f574d5e))
+
 ## [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)
 
 ### Dependencies

package/index.ts

@@ -26,9 +26,10 @@ Supported facade runtime modes:
 ${SETUP_MODE_CONTEXT}
 
 For agent-driven flows, use the installed \`n8n-manager\` and \`n8n-architect\`
-skills and their documented shell commands. Instance/auth/project management
-belongs to \`n8n-manager\`; context-root overrides and workflow sync belong
-to \`n8nac workspace\` and the n8n-as-code skills.
+skills and their documented shell commands. Local managed runtime lifecycle
+belongs to \`n8n-manager\`; environment/project/auth/workflowsPath management
+uses V4 \`n8nac env\` commands such as \`env add\`, \`env update\`, and
+\`env auth set\`, and workflow sync uses the n8n-as-code skills.
 `;
 
 function buildStatusHeader(workspaceDir: string): string {
@@ -39,13 +40,13 @@ function buildStatusHeader(workspaceDir: string): string {
     "**The context root is initialized. Do NOT infer effective n8n config from this prompt.**",
     "",
     `- Context root: \`${workspaceDir}\``,
-    `- Local overrides file: \`${join(workspaceDir, "n8nac-config.json")}\``,
+    `- Workspace environment file: \`${join(workspaceDir, "n8nac-config.json")}\``,
     `- Bootstrap file: \`${join(workspaceDir, "AGENTS.md")}\``,
     "",
-    "Before n8n work, run `n8nac workspace status --json` from the context root and use the backend-resolved result.",
-    cfg.activeInstanceId || cfg.projectId || cfg.projectName || cfg.syncFolder
-      ? "The local overrides file exists, but n8n-manager plus n8nac backend resolution remains the only source of effective state."
-      : "The local overrides file is present but incomplete.",
+    "Before n8n work, run `n8nac env status --json` from the context root and use the backend-resolved result.",
+    cfg.environmentId || cfg.workflowsPath
+      ? "The workspace environment file exists, but n8nac backend resolution remains the only source of effective state."
+      : "The workspace environment file is present but incomplete.",
   ].join("\n");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n-as-code/n8nac",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
   "keywords": [
     "n8n",

package/skills/n8n-architect/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user explicitly wants to create, edit, validate, sync,
 
 # n8n Architect
 
-Use this skill for all n8n-as-code work: workspace readiness, migration, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.
+Use this skill for all n8n-as-code work: workspace readiness, environments, managed local instances, tunnels, workflow authoring, validation, sync, push, and pull.
 
 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.
 
@@ -30,41 +30,15 @@ npx --yes n8nac env status --json
 
 ## Workspace Readiness
 
-Use the unified migration preflight before resolving the effective environment. The dry-run is safe and reports whether any workspace migration is required:
+Resolve the effective environment through the backend before workflow work:
 
 ```bash
-npx --yes n8nac workspace migrate --json
 npx --yes n8nac env status --json
 ```
 
-- Treat `workspace migrate --json` as the source of migration need.
-- Treat `env status --json` as the source of effective workspace readiness only after migration is not required or has been applied.
+- Treat `env status --json` as the source of effective workspace readiness.
 - Do not infer readiness from raw files, generated agent docs, or directory names.
-- 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.
-
-## Migration
-
-Migration is one user-facing command. Do not reason about internal migration phases directly; summarize the report `operations` array when explaining what will change.
-
-1. Run the dry-run first:
-
-```bash
-npx --yes n8nac workspace migrate --json
-```
-
-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.
-3. After confirmation, apply migration and re-check readiness:
-
-```bash
-npx --yes n8nac workspace migrate --write
-npx --yes n8nac workspace migrate --json
-npx --yes n8nac env status --json
-```
-
-- Do not run `workspace migrate --write` without explicit confirmation unless the user already directly requested applying migration.
-- When reporting a dry-run, summarize the unified `operations` list and ask for exactly one confirmation for `npx --yes n8nac workspace migrate --write`.
-- Do not ask separately for different operation types. `npx --yes n8nac workspace migrate --write` applies the required migration as one operation.
-- Do not run environment, workflow, or setup commands while `workspace migrate --json` still reports migration required.
+- 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.
 - Managed local instances remain machine-global runtime resources.
 - Workspace environments remain workspace-scoped and are managed through `npx --yes n8nac env ...`.
 
@@ -72,14 +46,12 @@ npx --yes n8nac env status --json
 
 1. `cd` to the context root.
 2. Run `npx --yes n8nac update-ai`, then read `AGENTS.md`.
-3. Run `npx --yes n8nac workspace migrate --json`.
-4. If migration is required, stop and ask for confirmation before `npx --yes n8nac workspace migrate --write` unless the user already requested applying migration.
-5. Run `npx --yes n8nac env status --json` after migration is not required or has been applied.
-6. If the context root is not ready, inspect managed local instances with `npx --yes @n8n-as-code/n8n-manager instance list`.
-7. Reuse an existing environment or managed local instance when suitable.
-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.
-9. Ask for host/API key only for an explicitly remote n8n environment.
-10. Configure the environment with:
+3. Run `npx --yes n8nac env status --json`.
+4. If the context root is not ready, inspect managed local instances with `npx --yes @n8n-as-code/n8n-manager instance list`.
+5. Reuse an existing environment or managed local instance when suitable.
+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.
+7. Ask for host/API key only for an explicitly remote n8n environment.
+8. Configure the environment with:
 
 ```bash
 npx --yes n8nac env add <name> --base-url <url> --workflows-path workflows/<name>
@@ -94,7 +66,7 @@ npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows
 npx --yes n8nac env use Local
 ```
 
-11. Run `npx --yes n8nac update-ai` after changing environments when the facade does not do it automatically.
+9. Run `npx --yes n8nac update-ai` after changing environments when the facade does not do it automatically.
 
 ## Environments
 

package/src/workspace.ts

@@ -3,16 +3,18 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 export type WorkspaceBinding = {
+  activeEnvironmentId?: string;
+  environmentId?: string;
+  environmentName?: string;
+  workflowsPath?: string;
   projectId?: string;
   projectName?: string;
-  syncFolder?: string;
-  activeInstanceId?: string;
 };
 
 /**
- * Fixed context-root directory for V1.
+ * Fixed context-root directory for n8n-as-code.
  * All n8nac context files (n8nac-config.json, AGENTS.md, .agents/skills, workflows/) live here.
- * n8n instances and credentials are stored globally by n8n-manager.
+ * Runtime access is resolved through V4 workspace environments.
  */
 export function getWorkspaceDir(): string {
   return join(homedir(), ".openclaw", "n8nac");
@@ -31,12 +33,21 @@ export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
   try {
     const raw = readFileSync(configPath, "utf-8");
     const config = JSON.parse(raw) as Record<string, unknown>;
+    if (config.version !== 4) return {};
+    const environments = Array.isArray(config.environments) ? config.environments as Array<Record<string, unknown>> : [];
+    const activeEnvironmentId = readString(config.activeEnvironmentId);
+    const environment = activeEnvironmentId
+      ? environments.find((item) => readString(item.id) === activeEnvironmentId)
+      : environments[0];
+    if (!environment) return { activeEnvironmentId: activeEnvironmentId || undefined };
 
     return {
-      projectId: readString(config.projectId) || undefined,
-      projectName: readString(config.projectName) || undefined,
-      syncFolder: readString(config.syncFolder) || undefined,
-      activeInstanceId: readString(config.activeInstanceId) || undefined,
+      activeEnvironmentId: activeEnvironmentId || undefined,
+      environmentId: readString(environment.id) || undefined,
+      environmentName: readString(environment.name) || undefined,
+      workflowsPath: readString(environment.workflowsPath) || undefined,
+      projectId: readString(environment.projectId) || undefined,
+      projectName: readString(environment.projectName) || undefined,
     };
   } catch {
     return {};
@@ -45,9 +56,9 @@ export function readWorkspaceBinding(workspaceDir: string): WorkspaceBinding {
 
 /**
  * Returns true when n8nac has been initialized in the given directory,
- * meaning the config exists and contains a selected project + sync folder.
+ * meaning the config exists and contains an active V4 environment with workflowsPath.
  */
 export function isWorkspaceInitialized(workspaceDir: string): boolean {
   const binding = readWorkspaceBinding(workspaceDir);
-  return Boolean(binding.projectId && binding.projectName && binding.syncFolder);
+  return Boolean(binding.environmentId && binding.workflowsPath);
 }