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

.gitattributes

@@ -0,0 +1,3 @@
+*.sh text eol=lf
+*.zig text eol=lf
+*.zon text eol=lf

.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,41 @@
+#!/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
+  shell_markers='shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS'
+  case "$(uname -s)" in
+    MINGW*|MSYS*|CYGWIN*)
+      ;;
+    *)
+      shell_markers="${shell_markers}|cmd\\.exe|sh -c"
+      ;;
+  esac
+  if strings "${bin}" | grep -E "${shell_markers}"; 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.