@dot-agent/cli 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Publish package to npm
+        run: npm publish

package/AGENTS.md

@@ -0,0 +1,94 @@
+# Agent Dependencies
+
+This document tracks dependencies between agents built with the `dot-agent` CLI and external agent services.
+
+## Structure
+
+Each agent that requires services from other agents or external APIs should be documented below with:
+- **Agent ID** — Qualified name (domain/name:version)
+- **Requires** — List of agent services or APIs needed
+- **Status** — Deployment or development status
+- **Notes** — Additional context or constraints
+
+## Template
+
+When adding a new agent, use this format:
+
+```markdown
+### agent-name (domain/agent-name:v1.0)
+
+**Requires:**
+- `ServiceAgent` — Provides X functionality
+- External API: `https://api.example.com` — Rate limited to 100 req/min
+
+**Status:** Development
+
+**Notes:** Add any important integration notes, authentication requirements, or deployment constraints.
+```
+
+---
+
+## Example Agents
+
+### doctor (entelekheia.ai/doctor:v1.0)
+
+**Requires:**
+- `UserProfile` — Patient data and medical history
+- EMR API — Electronic medical records system
+
+**Status:** Production
+
+**Notes:** 
+- Requires HIPAA compliance verification
+- Patient consent tokens must be present in context
+- Knowledge base includes latest clinical guidelines
+
+---
+
+### assistant (example.com/assistant:v1.0)
+
+**Requires:**
+- `FileSystem` — Read/write operations
+- `SearchAPI` — Query external knowledge bases
+
+**Status:** Development
+
+**Notes:** Early prototype, not for production use yet
+
+---
+
+## Common Dependencies
+
+### System Capabilities
+
+- **UserProfile** — User identity, preferences, history
+- **FileSystem** — Disk I/O, document storage
+- **Memory** — Session/context memory (internal)
+- **Clock** — Time-aware features
+
+### External Integrations
+
+- **SearchAPI** — Web search or knowledge base queries
+- **EmailService** — Send/receive emails
+- **SlackBot** — Slack workspace integration
+- **PaymentGateway** — Transaction processing
+
+---
+
+## Orchestration Rules
+
+When composing agents that have dependencies:
+
+1. **Initialization Order** — Load agents bottom-up (services before clients)
+2. **Error Handling** — Graceful degradation if optional dependencies unavailable
+3. **Timeout Policy** — Set reasonable timeouts for inter-agent calls
+4. **Logging** — Log all external service calls for debugging
+
+---
+
+## Notes for Developers
+
+- Update this file when adding new agents or changing dependencies
+- Document breaking changes when upgrading agent versions
+- Use semantic versioning (v1.0, v2.1, etc.) for reproducibility
+- Keep a `requires[]` field in your agent's `.description` file in sync with this document

package/README.md

@@ -0,0 +1,263 @@
+# dot-agent CLI
+
+The official command-line interface for the **dot-agent** specification. Build, validate, package, and execute AI agents with a simple, declarative DSL.
+
+## Installation
+
+```bash
+npm install -g dot-agent
+```
+
+Or use directly with `npx`:
+
+```bash
+npx dot-agent <command>
+```
+
+## Quick Start
+
+### 1. Initialize a new agent project
+
+```bash
+dot-agent init --name my-agent --domain example.com --dir ./my-agent
+```
+
+This creates a scaffold with:
+- `agent.description` — Agent manifest (domain, name, capabilities)
+- `agent.behavior` — FSM state machine definition
+- `SOUL.md` — Agent persona and voice
+- `README.md`, `LICENSE` — Project metadata
+- `behaviors/`, `guides/`, `knowledge/` — Content directories
+
+### 2. Edit your agent
+
+Customize the generated files:
+- Describe your agent in `agent.description`
+- Define behavior states and transitions in `agent.behavior`
+- Add knowledge and guides as needed
+
+### 3. Package your agent
+
+```bash
+dot-agent pack --dir ./my-agent --version v1.0.0
+```
+
+This validates the DSL and creates `my-agent.agent` (a ZIP archive) with:
+- `.agent/aboutme.json` — Agent metadata
+- `.agent/files.json` — File manifest
+- Source files and content
+
+### 4. Run your agent
+
+```bash
+dot-agent run ./my-agent.agent
+```
+
+Loads the agent and returns an `AgentContext` for execution in Electron, Node, or another runtime.
+
+### 5. Extract an agent (optional)
+
+```bash
+dot-agent unpack my-agent.agent --out ./unpacked
+```
+
+Restores the original source files from a `.agent` package.
+
+---
+
+## Commands
+
+| Command | Purpose | Example |
+|---------|---------|---------|
+| `init` | Scaffold a new agent project | `dot-agent init --name myagent --domain example.com` |
+| `pack` | Validate and package agent into `.agent` ZIP | `dot-agent pack --dir . --version v1.0.0` |
+| `unpack` | Extract `.agent` file to sources | `dot-agent unpack myagent.agent --out ./src` |
+| `run` | Load agent and return AgentContext | `dot-agent run myagent.agent` |
+
+---
+
+## Agent Definition
+
+### `agent.description`
+
+Declares the agent's identity, capabilities, and requirements:
+
+```
+agent MyAgent
+  domain example.com
+  license Apache-2.0
+
+description
+  A helpful AI assistant for customer support.
+
+behavior agent.behavior
+
+capabilities
+  RespondToQuery "Answer customer questions"
+  EscalateToHuman "Transfer to human agent when needed"
+```
+
+### `agent.behavior`
+
+Defines the finite state machine (FSM) that governs agent behavior:
+
+```
+state init
+  transition to ready
+
+state ready
+  goal "Help the user with their query."
+  interact
+  on intent "ask-question" transition to answering
+  on intent "escalate" transition to escalated
+
+state answering
+  goal "Provide a helpful answer."
+  interact
+  on intent "follow-up" transition to answering
+  on intent "resolved" transition to ready
+
+state escalated
+  goal "Transfer conversation to human support."
+  transition to ready
+```
+
+---
+
+## API Usage
+
+Use `dot-agent` as a module in Node.js or Electron:
+
+```typescript
+import { init, pack, unpack, run } from 'dot-agent'
+
+// Initialize a project
+const initResult = await init({
+  name: 'my-agent',
+  domain: 'example.com',
+  dir: './agents/my-agent'
+})
+
+// Package an agent
+const packResult = await pack({
+  dir: './agents/my-agent',
+  version: 'v1.0.0'
+})
+console.log(`Agent packaged: ${packResult.id}`)
+
+// Load an agent
+const context = await run({
+  source: './my-agent.agent'
+})
+
+// Listen to loading progress
+context.on('progress', (event) => {
+  console.log(`${event.step}: ${event.pct}%`)
+})
+
+context.on('ready', (ctx) => {
+  console.log(`Agent ready: ${ctx.id}`)
+})
+```
+
+---
+
+## Package Format (.agent)
+
+A `.agent` file is a ZIP archive containing:
+
+```
+my-agent.agent (ZIP)
+├── .agent/
+│   ├── aboutme.json        ← Agent metadata (required)
+│   ├── files.json          ← File manifest
+│   └── types.json          ← Type definitions (optional)
+├── agent.description       ← Agent manifest
+├── agent.behavior          ← FSM definition
+├── behaviors/              ← Behavior includes
+├── guides/                 ← Procedural guides
+├── knowledge/              ← Knowledge base / RAG
+└── SOUL.md                 ← Agent persona
+```
+
+### `aboutme.json`
+
+```json
+{
+  "schemaVersion": "dot-agent/1.0",
+  "id": "example.com/my-agent:v1.0.0~a1b2c3d4",
+  "name": "My Agent",
+  "description": "A helpful AI assistant",
+  "version": "v1.0.0",
+  "domain": "example.com",
+  "license": "Apache-2.0",
+  "persona": "SOUL.md",
+  "compiler": "dot-agent/1.0.0",
+  "skills": [],
+  "requires": [],
+  "integrity": {
+    "sha256": "...",
+    "files": ".agent/files.json"
+  }
+}
+```
+
+---
+
+## Validation & Linting
+
+The `pack` command validates:
+
+1. **Syntax** — `.description` and `.behavior` DSL structure (tree-sitter)
+2. **Semantics** — FSM state references, memory access, capability definitions (kernel-dsl)
+3. **Files** — All referenced files exist and are readable
+
+Error codes:
+- `E001` — Missing required field in `.description`
+- `E003` — `.description` file not found
+- `E004` — Syntax error in `.behavior` DSL
+- `E006` — Semantic parse error in FSM
+- `E007` — `.behavior` file not found
+- `W003` — Domain still set to default `example.com`
+
+---
+
+## Requirements
+
+- **Node.js** 18.0.0 or higher
+- **npm** or compatible package manager
+
+## Dependencies
+
+- `@dot-agent/tree-sitter` — WASM-based DSL parser
+- `@dot-agent/kernel-dsl` — WASM-based FSM execution engine
+- `web-tree-sitter` — Tree-sitter bindings for web/Node.js
+- `jszip` — ZIP file creation and extraction
+
+---
+
+## Specification
+
+For the complete dot-agent specification, see:
+- [plan.md](./plan.md) — CLI design and implementation details
+- [file structure.md](./file%20structure.md) — `.agent` package format and semantics
+
+---
+
+## License
+
+Apache License 2.0 — See [LICENSE](./LICENSE) file
+
+## Author
+
+Danilo Borges — [https://daniloborg.es](https://daniloborg.es)
+
+---
+
+## Contributing
+
+Contributions welcome! Please file issues and PRs at the [main repository](https://github.com/dot-agent-spec/dot-agent).
+
+## Status
+
+**V1 Release Candidate** — All 4 core commands (`init`, `pack`, `unpack`, `run`) implemented and tested.