@n8n-as-code/n8nac 2026.3.1-next.12

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @n8n-as-code/n8nac
+
+## [2026.3.1](https://github.com/EtienneLescot/n8n-as-code/compare/@n8n-as-code/n8nac@v2026.3.0...@n8n-as-code/n8nac@v2026.3.1) (2026-03-13)
+
+### Documentation
+
+* align editor and integration release messaging ([e1d6198](https://github.com/EtienneLescot/n8n-as-code/commit/e1d6198c3c6c942afe024f34b4ad419005ed991c))

package/README.md

@@ -0,0 +1,163 @@
+# @n8n-as-code/n8nac
+
+**OpenClaw-native access to the `n8n-as-code` workflow stack.**
+
+Use OpenClaw to build, update, validate, and manage n8n workflows with the same `n8nac` CLI and AI context model used across the wider `n8n-as-code` project.
+
+## Install
+
+```bash
+openclaw plugins install @n8n-as-code/n8nac
+```
+
+If you previously installed `@n8n-as-code/openclaw-plugin`, remove the old install first so OpenClaw re-registers the plugin cleanly under `n8nac`:
+
+```bash
+openclaw plugins uninstall n8nac
+openclaw plugins install @n8n-as-code/n8nac
+```
+
+Restart the gateway, then run the setup wizard:
+
+```bash
+openclaw n8nac:setup
+```
+
+The wizard asks for your n8n host URL and API key once, saves them via
+`n8nac init-auth`, selects your project, and generates an AI context file
+(`AGENTS.md`) in the workspace (`~/.openclaw/n8nac/`).
+
+## Usage
+
+Once setup is done, just talk to OpenClaw:
+
+> "Create an n8n workflow that sends a Slack message when a GitHub issue is opened"
+
+> "Pull workflow 42 and add an error handler to it"
+
+> "What operations does the Google Sheets node support?"
+
+The plugin injects the full n8n-architect instructions into every conversation
+so the AI knows the exact `n8nac` workflow (init-check → pull → edit → push → verify).
+
+## CLI commands
+
+| Command | Description |
+|---|---|
+| `openclaw n8nac:setup` | Interactive setup wizard |
+| `openclaw n8nac:status` | Show workspace status |
+
+Options for `n8nac:setup`:
+
+```
+--host <url>          n8n host URL (skip prompt)
+--api-key <key>       n8n API key (skip prompt)
+--project-index <n>   Project to select non-interactively
+```
+
+## Workspace
+
+All files live in `~/.openclaw/n8nac/`:
+
+```
+~/.openclaw/n8nac/
+  n8nac-config.json     ← project binding (written by n8nac init-project)
+  AGENTS.md             ← AI context (written by n8nac update-ai)
+  workflows/            ← .workflow.ts files (your n8n workflows)
+```
+
+## Agent tool
+
+The plugin registers the `n8nac` tool with these actions:
+
+| Action | Description |
+|---|---|
+| `setup_check` | Check initialization state |
+| `init_auth` | Save n8n credentials |
+| `init_project` | Select n8n project |
+| `list` | List all workflows |
+| `pull` | Download a workflow by ID |
+| `push` | Upload a workflow file |
+| `verify` | Validate live workflow against schema |
+| `skills` | Run any `npx n8nac skills` subcommand |
+| `validate` | Validate a local `.workflow.ts` file |
+
+## Local development
+
+This section covers how to load the plugin from source during development so
+that changes take effect immediately without an npm publish cycle.
+
+### 1. Link the plugin directory
+
+OpenClaw's `--link` flag registers a local path instead of installing a copy.
+jiti is used to run TypeScript directly, so no build step is needed.
+
+```bash
+openclaw plugins install --link \
+  /home/etienne/repos/n8n-as-code/plugins/openclaw/n8n-as-code
+```
+
+What this does:
+- Adds the path to `plugins.load.paths` in `~/.openclaw/openclaw.json`
+- Registers a `source: "path"` install record bound to the plugin ID `n8nac`
+- No file copy — OpenClaw loads `index.ts` directly from the source tree
+
+### 2. Verify the plugin is registered
+
+```bash
+openclaw plugins info n8nac
+```
+
+You should see status `loaded` and the tool `n8nac` in the tools list.
+
+### 3. Run the setup wizard
+
+```bash
+openclaw n8nac:setup
+```
+
+Enter your n8n host and API key when prompted. The wizard writes
+`~/.openclaw/n8nac/n8nac-config.json` and generates `AGENTS.md`.
+
+### 4. Iterate on the code
+
+- Edit any `.ts` file in `plugins/openclaw/n8n-as-code/`
+- **Restart the gateway** to reload: `openclaw stop && openclaw start` (or the
+  equivalent service restart on your setup)
+- The `before_prompt_build` hook, tool schema, and CLI commands all reload on
+  gateway start
+
+### 5. Check gateway logs
+
+```bash
+tail -f ~/.openclaw/logs/openclaw-$(date +%Y-%m-%d).log | grep n8nac
+```
+
+The plugin prefixes all `api.logger` calls with `[n8nac]`.
+
+### 6. Inspect the n8nac workspace
+
+```
+~/.openclaw/n8nac/
+  n8nac-config.json   ← written by init-project
+  AGENTS.md           ← written by update-ai
+  workflows/          ← .workflow.ts files
+```
+
+To reset and redo setup from scratch:
+
+```bash
+rm -rf ~/.openclaw/n8nac && openclaw n8nac:setup
+```
+
+### 7. Unlink when done
+
+```bash
+openclaw plugins uninstall n8nac
+```
+
+---
+
+## Source
+
+Part of the [n8n-as-code](https://github.com/EtienneLescot/n8n-as-code) monorepo.

package/index.ts

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { registerN8nAcCli } from "./src/cli.js";
+import { createN8nAcTool } from "./src/tool.js";
+import { getWorkspaceDir, isWorkspaceInitialized } from "./src/workspace.js";
+
+// ---------------------------------------------------------------------------
+// AGENTS.md context injection — populated once on service start
+// ---------------------------------------------------------------------------
+
+const BOOTSTRAP_CONTEXT = `\
+## n8n-as-code — Bootstrap
+
+The n8n-as-code plugin is installed but the workspace has not been initialized yet.
+
+**Tell the user:**
+> "To start building n8n workflows I need your n8n host URL and API key."
+
+Once you have both, call the \`n8nac\` tool with \`action: "init_auth"\`, then
+\`action: "init_project"\` to finish setup.
+`;
+
+const MISSING_AGENTS_CONTEXT = `\
+## n8n-as-code — AI Context Missing
+
+The workspace is initialized, but the generated AI context file (\`AGENTS.md\`) is missing or unreadable.
+
+**Tell the user:**
+> "Your n8n-as-code workspace is connected, but the AI context needs to be regenerated before I can safely guide workflow changes."
+
+Ask the user to run \`npx --yes n8nac update-ai\` in the OpenClaw workspace, or rerun
+\`openclaw n8nac:setup\` if they want the setup wizard to repair it.
+`;
+
+let agentsContext: string | null = null;
+
+function readConfig(workspaceDir: string): Record<string, string> {
+  try {
+    const raw = readFileSync(join(workspaceDir, "n8nac-config.json"), "utf-8");
+    return JSON.parse(raw) as Record<string, string>;
+  } catch {
+    return {};
+  }
+}
+
+function buildStatusHeader(workspaceDir: string): string {
+  const cfg = readConfig(workspaceDir);
+  const host = cfg.host ?? "(unknown)";
+  const project = cfg.projectName ?? cfg.projectId ?? "(unknown)";
+  return [
+    "## ✅ n8n-as-code Workspace Status",
+    "",
+    "**The workspace is already fully initialized. Do NOT ask the user for credentials.**",
+    "",
+    `- Workspace directory: \`${workspaceDir}\``,
+    `- n8n host: \`${host}\``,
+    `- Active project: \`${project}\``,
+    "",
+    "Skip the 'Workspace Bootstrap' section below — setup is complete.",
+    "Proceed directly to the user's request using the `n8nac` tool.",
+    "",
+    "---",
+    "",
+  ].join("\n");
+}
+
+function loadAgentsContext(workspaceDir: string): string | null {
+  const p = join(workspaceDir, "AGENTS.md");
+  if (!existsSync(p)) return null;
+  try {
+    const raw = readFileSync(p, "utf-8");
+    return buildStatusHeader(workspaceDir) + raw;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+const n8nAcPlugin = {
+  id: "n8nac",
+  name: "n8n-as-code",
+  description:
+    "Create and manage n8n workflows from OpenClaw using n8n-as-code (n8nac). " +
+    "Guides through workspace initialization, workflow CRUD, and AI-powered node schema lookup.",
+
+  register(api: OpenClawPluginApi) {
+    const workspaceDir = getWorkspaceDir();
+
+    // Ensure the plugin workspace directory always exists.
+    mkdirSync(workspaceDir, { recursive: true });
+
+    // -- Context injection ---------------------------------------------------
+    // Prepend n8n-architect instructions to every prompt build.
+    api.on("before_prompt_build", () => {
+      const initialized = isWorkspaceInitialized(workspaceDir);
+      // Lazy-load: setup may have run after the gateway started, so the
+      // service start() missed it.  Re-attempt on every prompt until loaded.
+      // The status header embeds host + project, so re-read on every call
+      // when not yet cached to pick up fresh config after setup.
+      if (agentsContext === null && initialized) {
+        agentsContext = loadAgentsContext(workspaceDir);
+      }
+      const context = agentsContext ?? (initialized ? MISSING_AGENTS_CONTEXT : BOOTSTRAP_CONTEXT);
+      if (!context) return;
+      return { prependContext: context };
+    });
+
+    // -- Agent tool ----------------------------------------------------------
+    api.registerTool(createN8nAcTool({ workspaceDir }));
+
+    // -- CLI wizard ----------------------------------------------------------
+    api.registerCli(
+      ({ program }) => registerN8nAcCli({ program, workspaceDir }),
+      { commands: ["n8nac:setup", "n8nac:status"] },
+    );
+
+    // -- Service -------------------------------------------------------------
+    // On gateway start: refresh the AGENTS.md cache so the agent always has
+    // up-to-date node knowledge.
+    api.registerService({
+      id: "n8nac-context",
+      start: async () => {
+        // Invalidate so next before_prompt_build re-reads from disk.
+        agentsContext = null;
+        if (isWorkspaceInitialized(workspaceDir)) {
+          agentsContext = loadAgentsContext(workspaceDir);
+          if (agentsContext) {
+            api.logger.info("[n8nac] Workspace ready — AI context loaded.");
+          } else {
+            api.logger.warn("[n8nac] Workspace ready, but AGENTS.md is missing or unreadable.");
+          }
+        } else {
+          api.logger.info("[n8nac] Workspace not initialized. Run `openclaw n8nac:setup`.");
+        }
+      },
+      stop: async () => {
+        agentsContext = null;
+      },
+    });
+  },
+};
+
+export default n8nAcPlugin;

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "n8nac",
+  "name": "n8n-as-code",
+  "description": "Create and manage n8n workflows from OpenClaw. Guides the AI through n8nac initialization and provides workflow tools.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": false,
+        "description": "Enable the n8n-as-code integration"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@n8n-as-code/n8nac",
+  "version": "2026.3.1-next.12",
+  "description": "OpenClaw plugin for n8n-as-code — create and manage n8n workflows from OpenClaw",
+  "keywords": [
+    "n8n",
+    "workflow",
+    "automation",
+    "openclaw",
+    "openclaw-plugin",
+    "n8nac"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EtienneLescot/n8n-as-code.git",
+    "directory": "plugins/openclaw/n8n-as-code"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "build": "npm run typecheck",
+    "clean": "rm -rf node_modules/.vitest",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "@sinclair/typebox": "0.34.48"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "^2026.2.26",
+    "typescript": "^5.8.0",
+    "vitest": "^1.6.1"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "README.md",
+    "index.ts",
+    "openclaw.plugin.json",
+    "src/",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.2.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/src/cli.ts

@@ -0,0 +1,266 @@
+import { mkdirSync } from "node:fs";
+import { spawn } from "node:child_process";
+import type { ChildProcess, ChildProcessWithoutNullStreams } from "node:child_process";
+import * as p from "@clack/prompts";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { isWorkspaceInitialized } from "./workspace.js";
+
+type CliProgram = Parameters<Parameters<OpenClawPluginApi["registerCli"]>[0]>[0]["program"];
+
+type CliOpts = {
+  program: CliProgram;
+  workspaceDir: string;
+};
+
+type RunResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+};
+
+function runN8nac(
+  args: string[],
+  opts: {
+    cwd: string;
+    timeout: number;
+    env?: NodeJS.ProcessEnv;
+    stdio?: "pipe" | "inherit";
+  },
+): Promise<RunResult> {
+  return new Promise((resolve) => {
+    const baseOptions = {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env },
+    };
+
+    const child: ChildProcess | ChildProcessWithoutNullStreams =
+      opts.stdio === "inherit"
+        ? spawn("npx", ["--yes", "n8nac", ...args], { ...baseOptions, stdio: "inherit" })
+        : spawn("npx", ["--yes", "n8nac", ...args], { ...baseOptions, stdio: "pipe" });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+
+    const finish = (result: RunResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve(result);
+    };
+
+    if ("stdout" in child && child.stdout) {
+      child.stdout.on("data", (chunk: Buffer) => {
+        stdout += chunk.toString();
+      });
+    }
+
+    if ("stderr" in child && child.stderr) {
+      child.stderr.on("data", (chunk: Buffer) => {
+        stderr += chunk.toString();
+      });
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        if (settled) return;
+        child.kill("SIGKILL");
+        finish({ stdout, stderr: stderr || "Process timed out.", exitCode: 1, timedOut: true });
+      }, 2_000);
+    }, opts.timeout);
+
+    child.on("error", (error: Error) => {
+      finish({ stdout, stderr: error.message || stderr, exitCode: 1, timedOut });
+    });
+
+    child.on("close", (code: number | null) => {
+      finish({ stdout, stderr, exitCode: code ?? 1, timedOut });
+    });
+  });
+}
+
+export function registerN8nAcCli({ program, workspaceDir }: CliOpts): void {
+  // -------------------------------------------------------------------------
+  // n8nac:status — quick health check
+  // -------------------------------------------------------------------------
+  program
+    .command("n8nac:status")
+    .description("Show n8n-as-code workspace status")
+    .action(() => {
+      const initialized = isWorkspaceInitialized(workspaceDir);
+      console.log(`\nn8n-as-code workspace: ${workspaceDir}`);
+      console.log(`Status: ${initialized ? "✓  Initialized" : "✗  Not initialized"}`);
+      if (!initialized) {
+        console.log("\nRun `openclaw n8nac:setup` to connect your n8n instance.");
+      }
+      console.log();
+    });
+
+  // -------------------------------------------------------------------------
+  // n8nac:setup — interactive wizard
+  // -------------------------------------------------------------------------
+  program
+    .command("n8nac:setup")
+    .description("Initialize or reconfigure the n8n-as-code workspace")
+    .option("--host <url>", "n8n host URL (skip prompt)")
+    .option("--api-key <key>", "n8n API key (skip prompt)")
+    .option("--project-index <n>", "Project index to select non-interactively")
+    .action(async (opts: { host?: string; apiKey?: string; projectIndex?: string }) => {
+      p.intro("n8n-as-code setup");
+
+      // Ensure workspace dir exists.
+      mkdirSync(workspaceDir, { recursive: true });
+      p.log.info(`Workspace: ${workspaceDir}`);
+
+      // ------------------------------------------------------------------
+      // Step 1: Collect credentials
+      // ------------------------------------------------------------------
+      let host = opts.host ?? "";
+      if (!host) {
+        const answer = await p.text({
+          message: "n8n host URL",
+          placeholder: "https://your-n8n.example.com",
+          validate: (v) => (v && v.startsWith("http") ? undefined : "Must start with http:// or https://"),
+        });
+        if (p.isCancel(answer)) {
+          p.cancel("Setup cancelled.");
+          process.exit(0);
+        }
+        host = answer as string;
+      }
+
+      let apiKey = opts.apiKey ?? "";
+      if (!apiKey) {
+        const answer = await p.password({
+          message: "n8n API key",
+          validate: (v) => (v && v.length > 0 ? undefined : "API key cannot be empty"),
+        });
+        if (p.isCancel(answer)) {
+          p.cancel("Setup cancelled.");
+          process.exit(0);
+        }
+        apiKey = answer as string;
+      }
+
+      // ------------------------------------------------------------------
+      // Step 2: init-auth
+      // ------------------------------------------------------------------
+      const authSpinner = p.spinner();
+      authSpinner.start("Saving credentials…");
+
+      const authResult = await runN8nac(["init-auth", "--host", host], {
+        cwd: workspaceDir,
+        timeout: 60_000,
+        env: { N8N_API_KEY: apiKey },
+      });
+
+      if (authResult.exitCode !== 0) {
+        authSpinner.stop("Failed to save credentials.");
+        if (authResult.timedOut) {
+          p.log.error("n8nac init-auth timed out.");
+        }
+        p.log.error(authResult.stderr || authResult.stdout || "Unknown error.");
+        p.outro("Setup failed. Check your host URL and API key and try again.");
+        process.exit(1);
+      }
+      authSpinner.stop("Credentials saved ✓");
+
+      // ------------------------------------------------------------------
+      // Step 3: init-project
+      // If the user passed --project-index, run non-interactively.
+      // Otherwise inherit stdio so n8nac's own interactive project picker can appear.
+      // ------------------------------------------------------------------
+      const projectSpinner = p.spinner();
+      const projectArgs = ["init-project", "--sync-folder", "workflows"];
+      let projectResult: RunResult;
+
+      if (opts.projectIndex) {
+        const projectIdx = Number.parseInt(opts.projectIndex, 10);
+        if (!Number.isInteger(projectIdx) || projectIdx < 1) {
+          p.log.error("--project-index must be a positive integer.");
+          p.outro("Setup failed.");
+          process.exit(1);
+        }
+        projectSpinner.start("Selecting project…");
+        projectResult = await runN8nac([...projectArgs, "--project-index", String(projectIdx)], {
+          cwd: workspaceDir,
+          timeout: 120_000,
+        });
+      } else {
+        projectSpinner.start("Opening project picker…");
+        projectSpinner.stop("Project picker ready");
+        projectResult = await runN8nac(projectArgs, {
+          cwd: workspaceDir,
+          timeout: 120_000,
+          stdio: "inherit",
+        });
+      }
+
+      if (projectResult.exitCode !== 0) {
+        projectSpinner.stop("Failed to select project.");
+        if (projectResult.timedOut) {
+          p.log.error("n8nac init-project timed out.");
+        }
+        p.log.error(projectResult.stderr || projectResult.stdout || "Unknown error.");
+        p.log.info("If you have multiple projects, rerun with --project-index <n>.");
+        p.outro("Setup failed.");
+        process.exit(1);
+      }
+      projectSpinner.stop("Project selected ✓");
+
+      // ------------------------------------------------------------------
+      // Step 4: update-ai — generate AGENTS.md
+      // ------------------------------------------------------------------
+      const aiSpinner = p.spinner();
+      aiSpinner.start("Generating AI context (AGENTS.md)…");
+      const aiResult = await runN8nac(["update-ai"], {
+        cwd: workspaceDir,
+        timeout: 60_000,
+      });
+
+      if (aiResult.exitCode !== 0) {
+        aiSpinner.stop("Failed to generate AI context.");
+        if (aiResult.timedOut) {
+          p.log.error("n8nac update-ai timed out.");
+        }
+        p.log.error(aiResult.stderr || aiResult.stdout || "Unknown error.");
+        p.outro(
+          "Setup partially completed: credentials and project were saved, but AGENTS.md generation failed. " +
+            "Run `npx --yes n8nac update-ai` after fixing the issue.",
+        );
+        process.exit(1);
+      }
+      aiSpinner.stop("AI context ready ✓");
+
+      p.log.step("What's next?");
+      p.log.message(
+        [
+          "  1. Restart the OpenClaw gateway to activate the plugin:",
+          "       openclaw gateway restart",
+          "",
+          "  2. Ask OpenClaw to create a workflow in plain language, for example:",
+          '       "Create an n8n workflow that sends a Slack message every morning"',
+          "",
+          "  3. Useful commands:",
+          "       openclaw n8nac:status   — check workspace + connection health",
+          "       openclaw n8nac:setup    — reconfigure host / API key",
+          "",
+          "  4. Manage workflows directly:",
+          "       npx n8nac list          — list local & remote workflows",
+          "       npx n8nac pull <id>     — download a workflow from n8n",
+          "       npx n8nac push <file>   — upload a workflow to n8n",
+        ].join("\n"),
+      );
+
+      p.outro(
+        `Setup complete!\n` +
+          `Workspace: ${workspaceDir}`,
+      );
+    });
+}

package/src/tool.ts

@@ -0,0 +1,363 @@
+import { spawn } from "node:child_process";
+import { Type } from "@sinclair/typebox";
+import { isWorkspaceInitialized } from "./workspace.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const ACTIONS = [
+  "setup_check",
+  "init_auth",
+  "init_project",
+  "list",
+  "pull",
+  "push",
+  "verify",
+  "skills",
+  "validate",
+] as const;
+
+const LIST_SCOPES = ["all", "local", "remote", "distant"] as const;
+
+const N8nAcToolSchema = Type.Object({
+  action: Type.Unsafe<(typeof ACTIONS)[number]>({
+    type: "string",
+    enum: [...ACTIONS],
+    description: [
+      "Action to perform:",
+      "  setup_check  — check whether the workspace is initialized.",
+      "  init_auth    — save n8n credentials. Requires n8nHost and n8nApiKey.",
+      "  init_project — select the n8n project. Optionally pass projectId, projectName, or projectIndex (1-based, default 1).",
+      "  list         — list all workflows with their sync status.",
+      "  pull         — download a workflow from n8n. Requires workflowId.",
+      "  push         — upload a local workflow file. Requires filename (e.g. my-flow.workflow.ts).",
+      "  verify       — fetch a workflow from n8n and validate it. Requires workflowId.",
+      "  skills       — run any n8nac skills subcommand. Requires skillsArgs (e.g. 'search telegram' or 'node-info googleSheets').",
+      "  validate     — validate a local workflow file. Requires validateFile.",
+    ].join("\n"),
+  }),
+  // init_auth
+  n8nHost: Type.Optional(
+    Type.String({ description: "n8n host URL (for init_auth). Example: https://your-n8n.example.com" }),
+  ),
+  n8nApiKey: Type.Optional(Type.String({ description: "n8n API key (for init_auth)" })),
+  // init_project
+  projectId: Type.Optional(Type.String({ description: "n8n project ID (for init_project)" })),
+  projectName: Type.Optional(Type.String({ description: "n8n project name (for init_project)" })),
+  projectIndex: Type.Optional(
+    Type.Number({ description: "n8n project index, 1-based (for init_project, default: 1)" }),
+  ),
+  listScope: Type.Optional(
+    Type.Unsafe<(typeof LIST_SCOPES)[number]>({
+      type: "string",
+      enum: [...LIST_SCOPES],
+      description: "Workflow list scope (for list). One of: all, local, remote, distant.",
+    }),
+  ),
+  // pull / verify
+  workflowId: Type.Optional(Type.String({ description: "Workflow ID (for pull, verify)" })),
+  // push
+  filename: Type.Optional(
+    Type.String({
+      description:
+        "Workflow filename including .workflow.ts extension (for push). " +
+        "Example: my-flow.workflow.ts. Do NOT pass a path.",
+    }),
+  ),
+  // skills
+  skillsArgs: Type.Optional(
+    Type.String({
+      description:
+        "Arguments for the n8nac skills subcommand (for skills action). " +
+        "Examples: 'search telegram', 'node-info googleSheets', 'examples search slack', 'docs OpenAI'",
+    }),
+  ),
+  skillsArgv: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Array form of arguments for the n8nac skills subcommand (preferred when values contain spaces). " +
+        'Example: ["examples", "search", "slack notification"]',
+    }),
+  ),
+  // validate
+  validateFile: Type.Optional(
+    Type.String({ description: "Workflow file path to validate (for validate action)" }),
+  ),
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+type RunResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  timedOut: boolean;
+};
+
+function runNpx(
+  args: string[],
+  cwd: string,
+  env?: NodeJS.ProcessEnv,
+): Promise<RunResult> {
+  return new Promise((resolve) => {
+    const child = spawn("npx", ["--yes", "n8nac", ...args], {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: "pipe",
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+    let killTimer: NodeJS.Timeout | undefined;
+
+    const finish = (result: RunResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      resolve(result);
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      killTimer = setTimeout(() => {
+        if (settled) return;
+        child.kill("SIGKILL");
+        finish({ stdout, stderr: stderr || "Process timed out.", exitCode: 1, timedOut: true });
+      }, 2_000);
+    }, 120_000);
+
+    child.on("error", (error) => {
+      finish({ stdout, stderr: error.message || stderr, exitCode: 1, timedOut });
+    });
+
+    child.on("close", (code) => {
+      finish({ stdout, stderr, exitCode: code ?? 1, timedOut });
+    });
+  });
+}
+
+function ok(data: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v.trim() : "";
+}
+
+export function splitArgv(input: string): string[] | null {
+  const args: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let escaping = false;
+
+  for (const ch of input) {
+    if (escaping) {
+      current += ch;
+      escaping = false;
+      continue;
+    }
+
+    if (ch === "\\" && quote !== "'") {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+
+    if (/\s/.test(ch)) {
+      if (current) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (escaping) current += "\\";
+  if (quote) return null;
+  if (current) args.push(current);
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createN8nAcTool(opts: { workspaceDir: string }) {
+  const { workspaceDir } = opts;
+
+  return {
+    name: "n8nac",
+    label: "n8n-as-code",
+    description:
+      "Create and manage n8n workflows using n8n-as-code. " +
+      "Handles workspace initialization (init_auth → init_project), " +
+      "workflow sync (list, pull, push, verify), and AI knowledge lookup (skills, validate). " +
+      "Always call setup_check first to determine initialization state.",
+    parameters: N8nAcToolSchema,
+
+    async execute(_toolCallId: string, params: Record<string, unknown>) {
+      const action = str(params.action);
+
+      // ---- setup_check --------------------------------------------------
+      if (action === "setup_check") {
+        const initialized = isWorkspaceInitialized(workspaceDir);
+        return ok({
+          initialized,
+          workspaceDir,
+          next: initialized
+            ? "Workspace is ready. Use list, pull, push, verify, or skills."
+            : "Workspace not initialized. Ask the user for their n8n host URL and API key, then call init_auth.",
+        });
+      }
+
+      // ---- init_auth ----------------------------------------------------
+      if (action === "init_auth") {
+        const host = str(params.n8nHost);
+        const key = str(params.n8nApiKey);
+        if (!host || !key) {
+          return ok({ error: "n8nHost and n8nApiKey are required for init_auth" });
+        }
+        const r = await runNpx(["init-auth", "--host", host], workspaceDir, { N8N_API_KEY: key });
+        if (r.exitCode !== 0) {
+          return ok({ error: r.stderr || r.stdout, exitCode: r.exitCode });
+        }
+        return ok({
+          ok: true,
+          output: r.stdout,
+          next: "Credentials saved. Now call init_project. If you need to inspect remote workflows first, use list with listScope: 'remote'.",
+        });
+      }
+
+      // ---- init_project -------------------------------------------------
+      if (action === "init_project") {
+        const id = str(params.projectId);
+        const name = str(params.projectName);
+        const idx = typeof params.projectIndex === "number" ? params.projectIndex : 1;
+        const args: string[] = ["init-project", "--sync-folder", "workflows"];
+        if (id) args.push("--project-id", id);
+        else if (name) args.push("--project-name", name);
+        else args.push("--project-index", String(idx));
+
+        const r = await runNpx(args, workspaceDir);
+        if (r.exitCode !== 0) {
+          return ok({ error: r.stderr || r.stdout, exitCode: r.exitCode });
+        }
+        // Refresh AGENTS.md after successful init
+        const ai = await runNpx(["update-ai"], workspaceDir);
+        if (ai.exitCode !== 0) {
+          return ok({
+            ok: true,
+            output: r.stdout,
+            warning: ai.stderr || ai.stdout || "AGENTS.md regeneration failed.",
+            next:
+              "Workspace initialized, but AI context regeneration failed. Run `npx --yes n8nac update-ai` before relying on agent-guided workflow work.",
+          });
+        }
+        return ok({
+          ok: true,
+          output: r.stdout,
+          next: "Workspace initialized. AGENTS.md regenerated. You can now list, pull, push, and verify workflows.",
+        });
+      }
+
+      // ---- list ---------------------------------------------------------
+      if (action === "list") {
+        const scope = str(params.listScope) || "all";
+        const args = ["list"];
+        if (scope === "local" || scope === "remote" || scope === "distant") {
+          args.push(`--${scope}`);
+        }
+        const r = await runNpx(args, workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- pull ---------------------------------------------------------
+      if (action === "pull") {
+        const id = str(params.workflowId);
+        if (!id) return ok({ error: "workflowId is required for pull" });
+        const r = await runNpx(["pull", id], workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- push ---------------------------------------------------------
+      if (action === "push") {
+        const file = str(params.filename);
+        if (!file) return ok({ error: "filename is required for push (e.g. my-flow.workflow.ts)" });
+        const r = await runNpx(["push", file, "--verify"], workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- verify -------------------------------------------------------
+      if (action === "verify") {
+        const id = str(params.workflowId);
+        if (!id) return ok({ error: "workflowId is required for verify" });
+        const r = await runNpx(["verify", id], workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- skills -------------------------------------------------------
+      if (action === "skills") {
+        const skillsArgv = Array.isArray(params.skillsArgv)
+          ? params.skillsArgv.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+          : [];
+        const skillsArgs = str(params.skillsArgs);
+        if (!skillsArgv.length && !skillsArgs) {
+          return ok({
+            error:
+              "skillsArgv or skillsArgs is required. Examples: skillsArgv: ['examples', 'search', 'slack notification']",
+          });
+        }
+        const parsedArgs = skillsArgv.length ? skillsArgv : splitArgv(skillsArgs);
+        if (!parsedArgs) {
+          return ok({ error: "skillsArgs contains an unterminated quote. Prefer skillsArgv when values contain spaces." });
+        }
+        const args = ["skills", ...parsedArgs];
+        const r = await runNpx(args, workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      // ---- validate -----------------------------------------------------
+      if (action === "validate") {
+        const file = str(params.validateFile);
+        if (!file) return ok({ error: "validateFile is required for validate" });
+        const r = await runNpx(["skills", "validate", file], workspaceDir);
+        return ok({ exitCode: r.exitCode, output: r.stdout, error: r.stderr || undefined });
+      }
+
+      return ok({ error: `Unknown action: ${action}` });
+    },
+  };
+}

package/src/workspace.ts

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Fixed workspace directory for V1.
+ * All n8nac files (n8nac-config.json, AGENTS.md, workflows/) live here.
+ */
+export function getWorkspaceDir(): string {
+  return join(homedir(), ".openclaw", "n8nac");
+}
+
+/**
+ * Returns true when n8nac has been initialized in the given directory,
+ * meaning the config exists and contains a selected project + sync folder.
+ */
+export function isWorkspaceInitialized(workspaceDir: string): boolean {
+  const configPath = join(workspaceDir, "n8nac-config.json");
+  if (!existsSync(configPath)) return false;
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw) as Record<string, unknown>;
+    const projectId = typeof config.projectId === "string" ? config.projectId.trim() : "";
+    const projectName = typeof config.projectName === "string" ? config.projectName.trim() : "";
+    const syncFolder = typeof config.syncFolder === "string" ? config.syncFolder.trim() : "";
+    return projectId.length > 0 && projectName.length > 0 && syncFolder.length > 0;
+  } catch {
+    return false;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2023"
+  },
+  "include": ["index.ts", "src/**/*", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}