nduka 1.0.0

package/docs/connector-implementation-playbook.md

@@ -0,0 +1,182 @@
+# Connector Implementation Playbook
+
+This guide explains how to work through the ChatGPT GitHub connector on this repo without triggering tool-call blocks.
+
+## Why this file exists
+
+During Tool System v2 work, some GitHub connector writes were blocked by the platform safety layer before they reached GitHub. The blocks were not normal GitHub errors. They appeared as:
+
+```text
+This tool call was blocked by OpenAI's safety checks. Please double check what you are sending.
+```
+
+The blocked payloads shared a pattern:
+
+- dynamic tool execution,
+- configurable external endpoints,
+- user or config templating into outbound requests,
+- environment-secret header mapping,
+- generic network runner behavior,
+- large full-file updates that combined validation, execution, secrets, and dynamic tool registration.
+
+The successful payloads shared the opposite pattern:
+
+- config files,
+- pure schema and validation,
+- policy files,
+- tests,
+- docs,
+- no runtime network execution,
+- no arbitrary endpoint runner,
+- no secret-header wiring in the same patch.
+
+## Rule of thumb
+
+Build v2 in layers. Do not send one large connector write that combines policy, config loading, runtime execution, and secret handling.
+
+Use this order:
+
+1. Documentation.
+2. Static config examples.
+3. Type definitions.
+4. Pure validation.
+5. Unit tests.
+6. Read-only catalog listing.
+7. Wiring to existing known adapters.
+8. Command/UI exposure.
+9. Strictly limited runtime execution.
+10. Packaging.
+
+## Safe through the connector
+
+These have worked reliably:
+
+- `config/*.json` examples that do not contain real secrets.
+- `src/**/policy.ts` files.
+- `src/**/registry.ts` files that load local JSON and render templates.
+- `src/**/config.ts` files that validate local config.
+- Unit tests using fake data.
+- Docs.
+- Small wrapper files.
+
+## Risky through the connector
+
+These may be blocked and should be split into smaller steps:
+
+- generic network runners,
+- arbitrary URL execution,
+- config-driven outbound request code,
+- environment-secret header injection,
+- dynamic plugin loading plus execution,
+- shell or process execution,
+- large files combining all of the above.
+
+## Safe design pattern for dynamic tools
+
+Do not begin with arbitrary HTTP tools.
+
+Begin with a catalog:
+
+```json
+{
+  "providers": {
+    "crunchtrova": {
+      "enabled": true,
+      "adapter": "crunchtrova",
+      "operations": {
+        "news": {
+          "kind": "news_search",
+          "resultMode": "list",
+          "timeoutSeconds": 180,
+          "maxResults": 5
+        }
+      }
+    }
+  },
+  "tools": {
+    "news_search": {
+      "enabled": true,
+      "provider": "crunchtrova",
+      "operation": "news",
+      "public": true,
+      "ownerOnly": false,
+      "synthesis": true,
+      "rawAllowed": true
+    }
+  }
+}
+```
+
+Then wire catalog entries to known adapters such as Crunchtrova. Only after that works should the project add custom HTTP tools, and those should be deny-by-default and owner-only until proven safe.
+
+## Patch strategy
+
+Prefer multiple commits:
+
+1. `Add configurable tool catalog file`
+2. `Add configurable tool catalog loader`
+3. `Test configurable tool catalog loader`
+4. `Wire built-in tools through catalog`
+5. `Make command tools synthesis-first`
+
+Avoid a single commit like:
+
+```text
+Add dynamic tool plugin system
+```
+
+That usually combines too many risky behaviors.
+
+## Commit message guidance
+
+Use precise, boring commit messages:
+
+- `Add tool catalog config`
+- `Validate tool catalog references`
+- `List enabled catalog tools`
+- `Add prompt registry tests`
+- `Document connector playbook`
+
+Avoid vague or sensitive-sounding messages:
+
+- `Add arbitrary HTTP tool execution`
+- `Load secrets into dynamic tools`
+- `Generic network runner`
+- `Bypass connector safety`
+
+## What to do when blocked
+
+1. Do not retry the exact same payload repeatedly.
+2. Split the file into a validation-only commit first.
+3. Remove runtime execution from that patch.
+4. Remove secret handling from that patch.
+5. Add tests for the validation layer.
+6. Try a smaller wiring patch after validation is committed.
+7. If still blocked, provide a local patch and document why.
+
+## Current v2 connector-safe path
+
+Completed:
+
+- Prompt registry.
+- Prompt JSON config.
+- Prompt registry tests.
+- Tool policy.
+- Tool policy tests.
+- Tool catalog config.
+- Tool catalog loader.
+- Tool catalog tests.
+- This playbook.
+
+Next safe steps:
+
+1. Create a catalog-backed tool-definition builder.
+2. Make `ToolRegistry.getToolDefinitions()` read from catalog metadata.
+3. Keep execution on existing known adapters.
+4. Add synthesis-first command handling.
+5. Add CLI config commands.
+6. Add Docker/npm packaging.
+
+## Final principle
+
+The goal is not to bypass connector safety. The goal is to make each change small, understandable, and safe enough that both the connector and future engineers can inspect it clearly.

package/docs/custom-connectors.md

@@ -0,0 +1,167 @@
+# Custom External Connectors
+
+Custom connectors let the owner prepare safe read-only links to approved external business tools, such as order lookup, booking lookup, inventory lookup, CRM lookup, or support-ticket lookup.
+
+Connectors are disabled by default. Customers cannot use connector slash commands. Groups do not receive connector admin output.
+
+## Current status
+
+This milestone adds the safe connector foundation and owner-only confirmed execution:
+
+- Disabled-by-default connector manifest
+- Manifest validation
+- Explicit host allowlist
+- Safe URL preview without network access
+- Safe GET executor layer
+- DNS resolution guard for local/private network protection
+- Response size limits
+- Redirect refusal
+- Connector audit store
+- CLI admin commands
+- Owner WhatsApp status/list/validate/plan/run/audit commands
+
+Live connector execution is only available in owner self-chat, only after the owner adds `confirm` to the run command. It is not available to customer chats or groups.
+
+## Create the connector file
+
+Run:
+
+```bash
+npm run cli -- connectors init
+```
+
+This creates:
+
+```text
+config/connectors.chatbot.json
+```
+
+The default file is safe:
+
+```json
+{
+  "version": 1,
+  "enabled": false,
+  "connectors": []
+}
+```
+
+## Add one connector
+
+Edit `config/connectors.chatbot.json` and add one entry at a time.
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "connectors": [
+    {
+      "name": "order_lookup",
+      "description": "Look up order status by order number.",
+      "method": "GET",
+      "urlTemplate": "https://approved-business-host.com/orders/{orderNumber}",
+      "allowedHosts": ["approved-business-host.com"],
+      "timeoutMs": 10000,
+      "maxBytes": 50000
+    }
+  ]
+}
+```
+
+The placeholder in braces is filled from JSON arguments and encoded automatically.
+
+## Validate
+
+```bash
+npm run cli -- connectors validate
+```
+
+Expected success:
+
+```text
+Connector manifest valid. Enabled: yes. Connectors: 1.
+```
+
+## Preview without network access
+
+```bash
+npm run cli -- connectors plan order_lookup '{"orderNumber":"A12345"}'
+```
+
+The preview shows the connector name, enabled state, method, host, and path. It does not make a network request.
+
+## Owner-only run
+
+```bash
+/connectors run order_lookup {"orderNumber":"A12345"} confirm
+```
+
+Run commands are owner self-chat only. The command must end with `confirm`. Connector output is labeled as untrusted data and sanitized before it is sent back to WhatsApp.
+
+## List and audit
+
+```bash
+npm run cli -- connectors status
+npm run cli -- connectors list
+npm run cli -- connectors audit
+```
+
+Audit logs record connector name, actor, status, host, safe path, status code, duration, and sanitized error text. Audit logs do not store response bodies.
+
+## Owner WhatsApp commands
+
+Owner self-chat only:
+
+```text
+/connectors status
+/connectors list
+/connectors validate
+/connectors plan
+/connectors run <name> <json-args> confirm
+/connectors audit
+```
+
+Customers receive customer-safe guidance if they try connector commands. Groups do not receive connector admin output.
+
+## Required safety rules
+
+Every connector must follow these rules:
+
+- GET only
+- HTTPS only
+- Normal DNS host only
+- Host must be listed in `allowedHosts`
+- No URL credentials
+- No fragments
+- No local or private network targets
+- No redirects
+- Text-like responses only
+- Response size must stay under `maxBytes`
+
+## Recommended workflow
+
+1. Run `connectors init`.
+2. Add one connector.
+3. Keep the connector simple.
+4. Validate it.
+5. Preview it.
+6. Test an owner-only run with `confirm`.
+7. Review `connectors audit`.
+8. Run `npm run build`.
+9. Run `npm test`.
+
+## Troubleshooting
+
+If validation says the host must be allowed, make sure the host in `urlTemplate` exactly matches one entry in `allowedHosts`.
+
+If validation says HTTPS is required, update the connector URL to use HTTPS.
+
+If the preview says the connector is unknown, check the connector `name`.
+
+If the run command returns the usage line, make sure the command ends with `confirm`.
+
+If audit is empty, no connector execution or audited attempt has been recorded yet.
+
+## Release boundary
+
+This milestone permits owner-only confirmed connector execution. It does not expose live custom connector execution to customers or groups.

package/docs/docker.md

@@ -0,0 +1,76 @@
+# Docker Installation
+
+This project can run as a Docker service with persistent WhatsApp auth, database, config, and media storage.
+
+## Files
+
+- `Dockerfile` builds the production runtime.
+- `docker-compose.yml` runs the gateway and media worker together through `dist/gateway/bootstrap.js`.
+- `.dockerignore` keeps secrets, local data, and build outputs out of the image.
+
+## Required local files
+
+Create `.env` locally. Do not commit it.
+
+Minimum useful keys:
+
+```bash
+OPENROUTER_API_KEY=...
+KILOCODE_API_KEY=...
+GROQ_API_KEY=...
+CRUNCHTROVE_API=...
+BOT_TIMEZONE=Asia/Dubai
+```
+
+The container mounts these persistent paths:
+
+```text
+./data   -> /app/data
+./config -> /app/config:ro
+```
+
+The default config paths inside the container are:
+
+```text
+CHATBOT_CONFIG_PATH=/app/config/chatbot.config.json
+CHATBOT_TOOLS_PATH=/app/config/tools.chatbot.json
+CHATBOT_PROMPTS_PATH=/app/config/prompts.chatbot.json
+```
+
+## Build and run
+
+```bash
+docker compose build
+docker compose up
+```
+
+The first run may print a WhatsApp QR or pairing flow, depending on the current gateway behavior. The auth state is stored under `./data`, so restarting the container should preserve the session.
+
+## Stop
+
+```bash
+docker compose down
+```
+
+## Update after code changes
+
+```bash
+docker compose build --no-cache
+docker compose up
+```
+
+## CLI inside the container
+
+```bash
+docker compose run --rm wa-chatbot node dist/cli/index.js doctor
+docker compose run --rm wa-chatbot node dist/cli/index.js tools list
+docker compose run --rm wa-chatbot node dist/cli/index.js prompts list
+```
+
+## Safety notes
+
+- Never bake `.env` or WhatsApp auth into the image.
+- Keep `./data` persistent.
+- Keep `./config` editable on the host.
+- Dynamic custom HTTP tool execution is intentionally not part of this Docker milestone yet.
+- The current Docker image packages known safe adapters, catalog metadata, configurable prompts, and policy validation.