thinkwork-cli 0.12.12 → 0.12.15

package/dist/plugins/n8n/src/skills/n8n-workflow-operator/references/mcp-tooling.md

@@ -0,0 +1,40 @@
+# MCP Tooling
+
+Use live n8n MCP tools as the source of truth for tool names, argument shapes,
+node schemas, and current `typeVersion` values.
+
+## Tool Selection
+
+1. Search for nodes before configuring them.
+2. Read the node schema before setting parameters. Standard detail is enough for
+   most nodes; use deeper docs only when the required field is unclear.
+3. Validate nodes or workflows as soon as the tool surface supports it.
+4. Prefer partial workflow updates for edits to existing workflows. Include a
+   short intent when the tool accepts one.
+5. Fetch the workflow after create/update and inspect `connections`.
+
+## Node Type Formats
+
+Use the form expected by the tool being called:
+
+1. Node discovery and node validation tools use short forms, for example
+   `nodes-base.httpRequest`.
+2. Workflow JSON uses full forms, for example
+   `n8n-nodes-base.httpRequest`.
+3. If a tool returns both forms, carry both forward instead of reconstructing
+   from memory.
+
+## Credentials And Secrets
+
+1. Never emit fake credential ids such as `REPLACE_ME`.
+2. If the real credential id is unknown, omit the `credentials` block so the
+   native UI can show a usable selector.
+3. Never put tokens, API keys, or passwords in Set nodes, Code nodes,
+   expressions, or plain text fields. Use the n8n credential system.
+4. The ThinkWork agent-step bridge credential is separate from the n8n MCP
+   service credential.
+
+## Shortened Tool Names
+
+The ThinkWork runtime may expose long MCP tool names in shortened form. Choose
+tools by descriptions and parameter schemas, not memorized exact names.

package/dist/plugins/n8n/src/skills/n8n-workflow-operator/references/validation-and-handoff.md

@@ -0,0 +1,40 @@
+# Validation And Handoff
+
+Validation passing is necessary, not sufficient. A workflow can validate and
+still have wrong wires, missing branches, or unsafe runtime behavior.
+
+## Validation Loop
+
+1. Validate configured nodes when available.
+2. Create or update the inactive workflow.
+3. Validate the complete workflow.
+4. Fix one concrete error at a time, then validate again.
+5. Treat warnings as context-sensitive. Production workflows should address
+   missing error handling, retry, rate-limit, and credential warnings unless
+   there is a clear reason to accept them.
+
+## Verify After Write
+
+After every create or update:
+
+1. Fetch the workflow by id.
+2. Confirm workflow id, name, active state, tags, project or folder, trigger
+   nodes, credential references, and MCP access state.
+3. Inspect `connections` directly. Confirm each expected branch, error output,
+   and merge input is wired to the intended node.
+4. If multiple workflows match, stop and ask for the exact workflow id or URL.
+
+## Test Evidence
+
+1. Ask before any test that can create records, call external APIs, send
+   messages, or mutate production systems.
+2. Prefer disposable inputs and read-only endpoints.
+3. Record execution ids, failure messages, validation errors, and evidence
+   links in the handoff.
+
+## Handoff Checklist
+
+Include workflow id, workflow name, draft/test status, package requirements,
+credential assumptions, MCP access state, validation result, connection
+verification result, test evidence, and the native n8n UI action required from
+the shared operator.

package/dist/plugins/n8n/src/skills/n8n-workflow-operator/references/workflow-authoring.md

@@ -0,0 +1,45 @@
+# Workflow Authoring
+
+Build the smallest inactive draft that proves the requested automation shape,
+then validate and verify it before handoff.
+
+## Pattern Choice
+
+1. Manual trigger: use for user-triggered smoke tests and safe demos.
+2. Webhook: use when an external system pushes an event.
+3. Schedule: use for recurring fetch, report, and maintenance workflows.
+4. HTTP API integration: use for read/write calls to external REST APIs.
+5. Database sync: use for ETL and record reconciliation.
+6. AI agent: use when the workflow needs model reasoning or n8n agent tools.
+7. Batch processing: use when item count, pagination, or rate limits matter.
+
+## Construction Rules
+
+1. Prefer HTTP Request nodes over Code nodes for ordinary GET/POST calls.
+2. Prefer expressions in the consuming field for simple data mapping.
+3. Use `{{ ... }}` expressions in n8n fields. Use direct JavaScript only inside
+   Code nodes.
+4. Avoid Set/Edit Fields nodes that feed a single consumer; inline the
+   expression at the consuming field.
+5. For webhook workflows, user payload fields are under `$json.body`, not at
+   the root.
+6. For branchy workflows, reference upstream nodes by name instead of relying on
+   ambiguous `$json` at branch convergence.
+7. Search for existing workflows or templates before creating a larger reusable
+   workflow from scratch.
+
+## Draft Safety
+
+1. Keep created workflows inactive unless the human explicitly completes
+   production activation in the native n8n UI.
+2. Prefer disabled copies or disposable draft workflows for edits.
+3. Run only read-only or low-risk test executions without additional
+   confirmation.
+4. Do not trigger a production webhook, schedule, message send, database write,
+   or destructive external side effect as a smoke test.
+
+## Code Nodes
+
+Use Code nodes only for multi-item aggregation, allowlisted package use, or
+logic that cannot be expressed in fields. For Code nodes, use only packages
+declared in the Plugin Detail n8n custom package settings.

package/dist/plugins/n8n/terraform/n8n/README.md

@@ -0,0 +1,113 @@
+# n8n Terraform Module
+
+This module provisions the optional n8n managed-application runtime for
+ThinkWork.
+
+It creates:
+
+- A public HTTPS ALB for the n8n editor/webhook runtime.
+- One ECS/Fargate main service and one ECS/Fargate worker service.
+- A managed ElastiCache Valkey/Redis replication group for queue mode.
+- A retained S3 bucket or prefix for managed exports, package artifacts,
+  evidence, and optional future storage mode objects.
+- CloudWatch log groups, task/execution IAM roles, task security groups, and
+  Aurora ingress from the n8n tasks.
+- Secret references for the dedicated database credential, `N8N_ENCRYPTION_KEY`,
+  the shared native operator account, and the tenant service credential used by
+  the native n8n MCP integration.
+
+The runtime is deliberately parked by desired count. Set
+`runtime_enabled = false` to keep the database, cache, bucket, secrets, and ALB
+while stopping the n8n ECS services.
+
+## Storage Mode
+
+THNK-50 targets the self-hosted OSS n8n runtime. In queue mode, n8n workers do
+not support local filesystem binary storage, and n8n's S3/external execution
+storage is enterprise-gated. The default therefore stays honest:
+
+```hcl
+execution_data_storage_mode = "database"
+binary_data_mode            = "default"
+```
+
+The module still provisions S3 because ThinkWork needs retained package,
+evidence, export/import, and future storage artifacts. Licensed deployments can
+set the two storage-mode variables to `s3` after the deployment plan records the
+license/edition decision.
+
+## Database Lifecycle
+
+The module runs an idempotent managed-app database lifecycle hook before ECS task
+definitions are created. The hook uses `database_admin_secret_arn` to create the
+dedicated database/role when missing and to rotate the role password so it always
+matches `database_url_secret_arn` before runtime starts. The runtime secret must
+contain these JSON fields:
+
+```json
+{
+  "DATABASE_URL": "postgresql://thinkwork_n8n:...@host:5432/thinkwork_n8n?sslmode=require",
+  "DB_POSTGRESDB_PASSWORD": "..."
+}
+```
+
+The ECS task environment enables PostgreSQL SSL and sets
+`DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZED=false`. This keeps the Aurora connection
+encrypted while avoiding n8n startup failures when the container trust store does
+not include the AWS RDS CA bundle.
+
+Destroy runs the inverse hook after Terraform parks or removes the services:
+active n8n sessions are terminated, then the dedicated database and role are
+dropped. This keeps uninstall/reinstall verification loops from reusing stale
+database credentials.
+
+## Secrets
+
+Required runtime secrets:
+
+- `database_url_secret_arn`: `DATABASE_URL` and `DB_POSTGRESDB_PASSWORD`
+- `encryption_key_secret_arn`: `N8N_ENCRYPTION_KEY`
+- `operator_secret_arn`: `N8N_OPERATOR_EMAIL` and `N8N_OPERATOR_PASSWORD`
+- `service_credential_secret_arn`: `N8N_MCP_SERVICE_CREDENTIAL`
+
+`create_secret_placeholders = true` can create generated placeholders for
+fixtures or bootstrap flows. Production installs should pass real secret ARNs
+prepared by the managed-application workflow. Generated placeholder secrets use
+the documented name as an AWS `name_prefix` and force-delete on destroy so a
+failed or recently torn-down install can be recreated immediately without
+colliding with Secrets Manager pending-deletion tombstones.
+
+## Custom Packages
+
+`custom_package_specs` accepts exact public npm package specs such as
+`lodash@4.17.21` or `@scope/package@1.2.3`. The pinned specs are preserved for
+image-build evidence, while the runtime derives package names for
+`NODE_FUNCTION_ALLOW_EXTERNAL` so n8n Code nodes can import the installed
+packages.
+
+## Example
+
+```hcl
+module "n8n" {
+  source = "../../../plugins/n8n/terraform/n8n"
+
+  stage                = var.stage
+  vpc_id               = module.vpc.vpc_id
+  subnet_ids           = module.vpc.public_subnet_ids
+  cache_subnet_ids     = module.vpc.private_subnet_ids
+  db_security_group_id = module.database.db_security_group_id
+  database_host        = module.database.cluster_endpoint
+
+  public_url      = "https://n8n.example.com"
+  certificate_arn = aws_acm_certificate_validation.n8n.certificate_arn
+  image_uri       = "123456789012.dkr.ecr.us-east-1.amazonaws.com/n8n@sha256:..."
+
+  database_admin_secret_arn     = module.database.graphql_db_secret_arn
+  database_url_secret_arn       = aws_secretsmanager_secret.n8n_database.arn
+  encryption_key_secret_arn     = aws_secretsmanager_secret.n8n_encryption.arn
+  operator_secret_arn           = aws_secretsmanager_secret.n8n_operator.arn
+  service_credential_secret_arn = aws_secretsmanager_secret.n8n_service.arn
+  storage_bucket_name           = "thinkwork-dev-n8n"
+  runtime_enabled               = true
+}
+```