Initial commit

Author: Null-ai

.cursor/rules/nllclw.mdc

@@ -0,0 +1,6 @@
+---
+description: nllclw project instructions
+alwaysApply: true
+---
+
+Use `AGENTS.md` as the canonical project instructions for this repository.

.dockerignore

@@ -0,0 +1,4 @@
+.git
+.github
+.zig-cache
+zig-out

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Copilot Instructions
+
+Use `AGENTS.md` as the canonical project instructions for this repository.

.github/scripts/ci.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+zig fmt --check build.zig build.zig.zon src
+zig build test --summary all
+zig build test --summary all -Dshell-tool=true
+zig build --release=small
+
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*)
+    bin="./zig-out/bin/nllclw.exe"
+    ;;
+  *)
+    bin="./zig-out/bin/nllclw"
+    ;;
+esac
+"${bin}" --help >/dev/null
+
+if command -v strings >/dev/null 2>&1; then
+  if strings "${bin}" | grep -E 'shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS|cmd\.exe|sh -c'; then
+    echo "default binary contains shell-only strings"
+    exit 1
+  fi
+else
+  echo "strings is not available; skipping shell-only string scan"
+fi
+
+zig build --release=small -Dshell-tool=true
+zig build -Dtarget=x86_64-windows --release=small
+zig build -Dtarget=x86_64-linux --release=small
+zig build -Dtarget=aarch64-linux --release=small
+zig build -Dtarget=aarch64-macos --release=small
+zig build -Dtarget=wasm32-wasi --release=small

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  zig:
+    uses: nullclaw/nullbuilder/.github/workflows/zig-ci.yml@v1
+    permissions:
+      contents: read
+    with:
+      binary_name: nllclw
+      artifact_prefix: nllclw
+      zig_version: "0.16.0"
+      test_command: bash .github/scripts/ci.sh

.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  push:
+    tags: ["v20*"]
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    uses: nullclaw/nullbuilder/.github/workflows/zig-release.yml@v1
+    permissions:
+      contents: write
+      packages: write
+    with:
+      binary_name: nllclw
+      artifact_prefix: nllclw
+      zig_version: "0.16.0"
+      source_archive: true
+      publish_docker: true

.gitignore

@@ -0,0 +1,21 @@
+.zig-cache/
+zig-out/
+.env
+config.json
+USER.md
+BOOTSTRAP.md
+.nllclw-memory.jsonl
+.nllclw-memory.jsonl.lock
+.nllclw-memory.jsonl.tmp.*
+.nllclw-facts.jsonl
+.nllclw-facts.jsonl.lock
+.nllclw-facts.jsonl.tmp.*
+.nllclw-schedule.jsonl
+.nllclw-schedule.jsonl.lock
+.nllclw-schedule.jsonl.tmp.*
+.nllclw-user-tools.jsonl
+.nllclw-user-tools.jsonl.lock
+.nllclw-user-tools.jsonl.tmp.*
+.nllclw-telegram-offset
+.nllclw-telegram-offset.lock
+.nllclw-telegram-offset.tmp.*

AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+This is the canonical workspace instruction file for nllclw and for coding
+agents working on this repository. nllclw loads this file into runtime context
+when it is present in the current directory. Tool-specific files in this repo
+point here.
+
+## Project
+
+nllclw is a tiny Zig 0.16 AI assistant. It is intentionally stdlib-only by
+default: no package dependencies, no `curl`, no external runtime process, and no
+shell tool unless the binary is built with `-Dshell-tool=true`.
+
+## Architecture
+
+- `src/main.zig`: process entrypoint only.
+- `src/root.zig`: small public Zig package API.
+- `src/runtime.zig`: composition root for channels, config, adapters, memory, and tools.
+- `src/agent.zig`: channel-neutral Chat Completions engine.
+- `src/chat.zig`: OpenAI-compatible Chat Completions JSON/SSE codec.
+- `src/providers.zig`: OpenAI/OpenRouter/compatible endpoint and header presets.
+- `src/config/`: runtime config types, source mapping, and validation.
+- `src/channels/`: CLI, terminal REPL, local commands, Telegram, and WebSocket orchestration.
+- `src/tools/`: product tools: time, diagnostics, filesystem, memory, web search, scheduler, macro tools, and optional shell.
+- `src/ports/`: dependency ports.
+- `src/adapters/`: stdlib implementations of ports.
+
+Keep product capabilities in `src/tools/`, technical implementations in
+`src/adapters/`, and channel loops in `src/channels/`.
+
+## Build And Test
+
+Run these before handing work back:
+
+```sh
+zig fmt build.zig build.zig.zon $(find src -name '*.zig' -type f | sort)
+zig build test --summary all
+zig build test --summary all -Dshell-tool=true
+zig build --release=small
+./zig-out/bin/nllclw --help >/dev/null
+strings ./zig-out/bin/nllclw | rg 'shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS|cmd\.exe|sh -c' || true
+git diff --check
+```
+
+For portability-sensitive changes, also run:
+
+```sh
+zig build -Dtarget=x86_64-windows --release=small
+zig build -Dtarget=x86_64-linux --release=small
+zig build -Dtarget=aarch64-linux --release=small
+zig build -Dtarget=aarch64-macos --release=small
+zig build -Dtarget=wasm32-wasi --release=small
+```
+
+## Rules
+
+- Use Zig stdlib APIs first.
+- Preserve zero external runtime dependencies in the default binary.
+- Keep shell execution behind `-Dshell-tool=true`.
+- Do not expose channel/runtime internals from `src/root.zig`.
+- Add tests near the code for new behavior.
+- Update README metrics when release binary size, test counts, source file
+  counts, or LOC change.
+- When changing English documentation under `docs/en/`, apply the equivalent
+  documentation update to every translated language directory under `docs/`.
+- Do not commit `.env`, `config.json`, `USER.md`, `BOOTSTRAP.md`, or generated memory files.

CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Scope
+
+This code of conduct applies to the `nllclw` repository, issues, pull requests,
+reviews, discussions, and any maintainer-run project spaces.
+
+## Expected Behavior
+
+- Be respectful and direct.
+- Focus criticism on code, documentation, behavior, and tradeoffs.
+- Assume good intent when reasonable, and ask for clarification when something
+  is ambiguous.
+- Keep discussions relevant to the project and its users.
+- Protect private information, credentials, logs, tokens, and security reports.
+
+## Unacceptable Behavior
+
+- Harassment, threats, personal attacks, or sustained disruption.
+- Discriminatory language or behavior.
+- Publishing private information without explicit permission.
+- Sexualized comments or imagery in project spaces.
+- Deliberately misleading reports, malicious code, or attempts to bypass project
+  safety boundaries.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, reject contributions, or restrict
+repository access when behavior violates this code of conduct.
+
+If you need to report a conduct issue, contact a maintainer privately through
+GitHub. Include the relevant links, screenshots, or context needed to evaluate
+the report. Do not publish private or sensitive information in a public issue.

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing
+
+Thanks for improving `nllclw`. This project is intentionally small, stdlib-only
+by default, and conservative about local capabilities.
+
+## Development Setup
+
+Use Zig `0.16.0`.
+
+```sh
+zig version
+zig build test --summary all
+```
+
+The default binary must not require package dependencies, `curl`, Node, Python,
+an external runtime process, or a shell. Shell execution belongs only behind the
+explicit `-Dshell-tool=true` build option.
+
+## Before Submitting
+
+Run the repository gate:
+
+```sh
+zig fmt build.zig build.zig.zon $(find src -name '*.zig' -type f | sort)
+zig build test --summary all
+zig build test --summary all -Dshell-tool=true
+zig build --release=small
+./zig-out/bin/nllclw --help >/dev/null
+strings ./zig-out/bin/nllclw | rg 'shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS|cmd\.exe|sh -c' || true
+git diff --check
+```
+
+For portability-sensitive changes, also run the cross-builds listed in
+`AGENTS.md`.
+
+## Code Guidelines
+
+- Prefer Zig stdlib APIs before adding abstractions.
+- Keep product tools in `src/tools/`, adapters in `src/adapters/`, channel loops
+  in `src/channels/`, and runtime composition in `src/runtime.zig`.
+- Keep `src/main.zig` as the process entrypoint only.
+- Do not expose channel or runtime internals from `src/root.zig`.
+- Add focused tests near the code for new behavior.
+- Keep shell execution behind `-Dshell-tool=true`.
+- Preserve safe defaults for local files, memory, tools, Telegram, WebSocket,
+  and compatible-provider HTTP URLs.
+
+## Documentation
+
+- Prefer `config.json` examples for normal setup. Use environment variables for
+  one-off overrides, CI, or `.env` documentation.
+- Installation docs should recommend the latest release binary first, then
+  source builds with Zig `0.16.0`.
+- When changing English documentation under `docs/en/`, apply the equivalent
+  update to every translated language directory under `docs/`.
+
+## Secrets And Local State
+
+Do not commit:
+
+- `.env`
+- `config.json`
+- `USER.md`
+- `BOOTSTRAP.md`
+- generated memory files
+- provider keys, Telegram tokens, WebSocket tokens, or private logs
+
+If a contribution touches secret handling, local file access, shell execution,
+network endpoints, or provider configuration, call that out clearly in the pull
+request.