@anna-ai/cli 0.1.12 → 0.1.16

package/dist/storage-EQJA_0UW.js

@@ -0,0 +1,316 @@
+import { canonicalHost } from "./credentials-BTv2IfUZ.js";
+import { hostOf, requireAccount, withCode } from "./dev-account-DCyjamBa.js";
+import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+
+//#region src/executa/storage.ts
+/** JSON-RPC error codes from matrix/src/executa/protocol.py. */
+const STORAGE_ERR_INVALID_REQUEST = -32020;
+const STORAGE_ERR_NOT_GRANTED = -32021;
+const STORAGE_ERR_NOT_FOUND = -32022;
+const STORAGE_ERR_PRECONDITION_FAILED = -32023;
+const STORAGE_ERR_UPSTREAM = -32026;
+/** Method → (http_method, sub_path, payload_kind). Mirrors matrix/storage.py. */
+const ROUTING = {
+	"storage/get": [
+		"GET",
+		"/kv",
+		"query"
+	],
+	"storage/set": [
+		"PUT",
+		"/kv",
+		"body"
+	],
+	"storage/delete": [
+		"DELETE",
+		"/kv",
+		"query"
+	],
+	"storage/list": [
+		"GET",
+		"/list",
+		"query"
+	],
+	"files/upload_begin": [
+		"POST",
+		"/files/init",
+		"body"
+	],
+	"files/upload_complete": [
+		"POST",
+		"/files/finalize",
+		"body"
+	],
+	"files/download_url": [
+		"GET",
+		"/files/url",
+		"query"
+	],
+	"files/list": [
+		"GET",
+		"/files",
+		"query"
+	],
+	"files/delete": [
+		"DELETE",
+		"/files",
+		"query"
+	]
+};
+const VALID_SCOPES = new Set([
+	"user",
+	"app",
+	"tool"
+]);
+var StorageBridge = class {
+	mocks = [];
+	/** In-memory KV: `${scope}/${key}` → row. */
+	kv = new Map();
+	etagCounter = 0;
+	cachedToken = null;
+	constructor(opts) {
+		this.opts = opts;
+		if (opts.mode === "mock" && opts.mockFile) {
+			const path = resolve(opts.mockFile);
+			if (existsSync(path)) for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+				if (!line.trim() || line.startsWith("#")) continue;
+				try {
+					this.mocks.push(JSON.parse(line));
+				} catch {}
+			}
+		}
+	}
+	async call(method, params) {
+		if (!(method in ROUTING)) throw withCode(new Error(`unknown storage method: ${method}`), STORAGE_ERR_INVALID_REQUEST);
+		if (this.opts.mode === "off") throw withCode(new Error("storage disabled — rerun with `--storage memory|mock|real`"), STORAGE_ERR_NOT_GRANTED);
+		if (this.opts.mode === "mock") return this.mockCall(method, params);
+		if (this.opts.mode === "memory") return this.memoryCall(method, params);
+		return this.realCall(method, params);
+	}
+	mockCall(method, params) {
+		const [ns, shortName] = method.split("/", 2);
+		const content = String(params.key ?? params.path ?? params.prefix ?? "");
+		const matched = this.mocks.find((m) => m.ns === ns && m.method === shortName && (!m.match?.contentIncludes || content.includes(m.match.contentIncludes))) ?? this.mocks.find((m) => m.ns === ns && m.method === shortName);
+		if (matched) {
+			if (matched.error) throw withCode(new Error(matched.error.message), matched.error.code);
+			if (matched.result !== void 0) return matched.result;
+		}
+		if (method === "storage/get") throw withCode(new Error("key not found (mock)"), STORAGE_ERR_NOT_FOUND);
+		if (method === "storage/set") return {
+			ok: true,
+			etag: "mock-etag"
+		};
+		if (method === "storage/delete" || method === "files/delete") return { deleted: true };
+		if (method === "storage/list" || method === "files/list") return {
+			entries: [],
+			cursor: null
+		};
+		return {};
+	}
+	memoryCall(method, params) {
+		if (method.startsWith("files/")) throw withCode(new Error("memory storage backend does not support file objects — use `--storage mock <fixture>` (for canned responses) or `--storage real` (forwards to nexus)"), STORAGE_ERR_NOT_GRANTED);
+		const scope = coerceScope(params);
+		if (method === "storage/get") return this.memoryGet(scope, params);
+		if (method === "storage/set") return this.memorySet(scope, params);
+		if (method === "storage/delete") return this.memoryDelete(scope, params);
+		if (method === "storage/list") return this.memoryList(scope, params);
+		throw withCode(new Error(`unsupported storage method in memory mode: ${method}`), STORAGE_ERR_INVALID_REQUEST);
+	}
+	memoryGet(scope, params) {
+		const key = requireKey(params);
+		const row = this.kv.get(`${scope}/${key}`);
+		if (!row || expired(row)) {
+			if (row) this.kv.delete(`${scope}/${key}`);
+			return {
+				key,
+				value: null,
+				etag: null,
+				exists: false
+			};
+		}
+		return {
+			key,
+			value: row.value,
+			etag: row.etag,
+			exists: true
+		};
+	}
+	memorySet(scope, params) {
+		const key = requireKey(params);
+		if (!("value" in params)) throw withCode(new Error("'value' is required for storage/set"), STORAGE_ERR_INVALID_REQUEST);
+		const existing = this.kv.get(`${scope}/${key}`);
+		const ifMatch = params.if_match;
+		if (ifMatch !== void 0) {
+			const want = String(ifMatch);
+			const have = existing && !expired(existing) ? existing.etag : null;
+			if (have !== want && !(want === "" && !have)) throw withCode(new Error(`if_match mismatch (have=${have ?? "null"} want=${want})`), STORAGE_ERR_PRECONDITION_FAILED);
+		}
+		this.etagCounter += 1;
+		const etag = `mem-${this.etagCounter.toString(16)}`;
+		const ttlSec = Number(params.ttl_seconds ?? 0);
+		const row = {
+			value: params.value,
+			etag,
+			ttl_at: ttlSec > 0 ? Math.floor(Date.now() / 1e3) + ttlSec : null
+		};
+		this.kv.set(`${scope}/${key}`, row);
+		return {
+			ok: true,
+			key,
+			etag
+		};
+	}
+	memoryDelete(scope, params) {
+		const key = requireKey(params);
+		const existed = this.kv.delete(`${scope}/${key}`);
+		return { deleted: existed };
+	}
+	memoryList(scope, params) {
+		const prefix = String(params.prefix ?? "");
+		const limit = Math.min(1e3, Math.max(1, Number(params.limit ?? 100)));
+		const entries = [];
+		const wantPrefix = `${scope}/${prefix}`;
+		for (const [k, v] of this.kv.entries()) {
+			if (!k.startsWith(wantPrefix)) continue;
+			if (expired(v)) continue;
+			entries.push({
+				key: k.slice(scope.length + 1),
+				etag: v.etag
+			});
+			if (entries.length >= limit) break;
+		}
+		return {
+			entries,
+			cursor: null
+		};
+	}
+	/** Slug used for the synthetic executa app (real mode). */
+	resolvedSlug() {
+		if (this.opts.appSlug) return this.opts.appSlug;
+		const tool = this.opts.pluginName;
+		if (!tool) throw withCode(new Error("storage bridge has no app_slug AND no plugin tool_id — pass `--app-slug <slug>` or run from a directory whose executa spec exposes a tool_id"), -32602);
+		return tool.startsWith("executa-") ? tool : `executa-${tool}`;
+	}
+	async registerExecuta(host, pat, slug, tool) {
+		const url = `${host}/api/v1/anna-apps/dev/executas/register`;
+		const res = await fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				pat,
+				tool_id: tool,
+				slug
+			})
+		});
+		if (res.status === 404) throw withCode(new Error("your nexus does not expose POST /api/v1/anna-apps/dev/executas/register — upgrade nexus (matrix-nexus ≥ this CLI release) or use `--storage memory|mock`"), STORAGE_ERR_NOT_GRANTED);
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`dev/executas/register failed: HTTP ${res.status}: ${text}`), STORAGE_ERR_UPSTREAM);
+		}
+	}
+	async mintStorageToken() {
+		if (this.cachedToken && this.cachedToken.expiresAt - 30 > Math.floor(Date.now() / 1e3)) return this.cachedToken;
+		const acc = requireAccount(this.opts.account);
+		const slug = this.resolvedSlug();
+		const toolId = this.opts.pluginName ?? `dev-${slug}`;
+		const scopes = (this.opts.scopes ?? [
+			"user",
+			"app",
+			"tool"
+		]).filter((s) => VALID_SCOPES.has(s));
+		const body = {
+			pat: acc.pat,
+			app_slug: slug,
+			executa_tool_id: toolId,
+			allowed_scopes: scopes,
+			ttl_seconds: 600
+		};
+		const host = hostOf(acc);
+		const url = `${host}/api/v1/anna-apps/dev/storage/mint`;
+		const doMint = async () => fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body)
+		});
+		let res = await doMint();
+		if (res.status === 404) {
+			const peek = await res.clone().text().catch(() => "");
+			if (peek.includes("not found") && peek.includes(slug)) {
+				await this.registerExecuta(host, acc.pat, slug, toolId);
+				res = await doMint();
+			}
+		}
+		if (res.status === 404) throw withCode(new Error("your nexus does not expose POST /api/v1/anna-apps/dev/storage/mint — upgrade nexus (matrix-nexus ≥ this CLI release) or use `--storage memory|mock`"), STORAGE_ERR_NOT_GRANTED);
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			throw withCode(new Error(`dev/storage/mint failed: HTTP ${res.status}: ${text}`), STORAGE_ERR_UPSTREAM);
+		}
+		const out = await res.json();
+		this.cachedToken = {
+			token: out.storage_token,
+			expiresAt: Math.floor(Date.now() / 1e3) + (out.expires_in || 600),
+			allowedScopes: out.allowed_scopes ?? scopes
+		};
+		return this.cachedToken;
+	}
+	async realCall(method, params) {
+		const acc = requireAccount(this.opts.account);
+		const token = await this.mintStorageToken();
+		const route = ROUTING[method];
+		if (!route) throw withCode(new Error(`unknown storage method: ${method}`), STORAGE_ERR_INVALID_REQUEST);
+		const [httpMethod, subPath, kind] = route;
+		const scope = coerceScope(params);
+		const inner = {};
+		for (const [k, v] of Object.entries(params)) {
+			if (k === "scope") continue;
+			if (v === void 0) continue;
+			inner[k] = v;
+		}
+		const url = new URL(`${hostOf(acc)}/api/v1/storage${subPath}`);
+		url.searchParams.set("scope", scope);
+		let jsonBody;
+		if (kind === "query") for (const [k, v] of Object.entries(inner)) {
+			if (v === null) continue;
+			url.searchParams.set(k, typeof v === "string" ? v : JSON.stringify(v));
+		}
+		else jsonBody = JSON.stringify(inner);
+		const headers = { authorization: `Bearer ${token.token}` };
+		if (jsonBody !== void 0) headers["content-type"] = "application/json";
+		const res = await fetch(url, {
+			method: httpMethod,
+			headers,
+			body: jsonBody
+		});
+		if (!res.ok) {
+			const text = await res.text().catch(() => "");
+			const code = mapHttpStatusToStorageCode(res.status);
+			throw withCode(new Error(`HTTP ${res.status}: ${text}`), code);
+		}
+		const ct = res.headers.get("content-type") ?? "";
+		if ((method === "storage/delete" || method === "files/delete") && (res.status === 204 || !ct.includes("json"))) return { deleted: true };
+		return await res.json();
+	}
+};
+function coerceScope(params) {
+	const s = params.scope;
+	if (typeof s === "string" && VALID_SCOPES.has(s)) return s;
+	return "app";
+}
+function requireKey(params) {
+	const k = params.key;
+	if (typeof k !== "string" || !k) throw withCode(new Error("'key' is required (non-empty string)"), STORAGE_ERR_INVALID_REQUEST);
+	return k;
+}
+function expired(row) {
+	return row.ttl_at !== null && row.ttl_at < Math.floor(Date.now() / 1e3);
+}
+function mapHttpStatusToStorageCode(status) {
+	if (status === 401 || status === 403) return STORAGE_ERR_NOT_GRANTED;
+	if (status === 404) return STORAGE_ERR_NOT_FOUND;
+	if (status === 409 || status === 412) return STORAGE_ERR_PRECONDITION_FAILED;
+	return STORAGE_ERR_UPSTREAM;
+}
+
+//#endregion
+export { StorageBridge };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anna-ai/cli",
-  "version": "0.1.12",
+  "version": "0.1.16",
   "description": "Anna App developer CLI: scaffold, validate, harness (Phase 2 MVP: init + validate).",
   "license": "MIT",
   "type": "module",

package/templates/executa/go/README.md

@@ -0,0 +1,10 @@
+# __SLUG__
+
+A standalone Go Executa plugin scaffolded by `anna-app executa init`.
+
+## Develop locally
+
+```sh
+anna-app executa dev --describe
+anna-app executa dev --invoke ping
+```

package/templates/executa/go/executa.json

@@ -0,0 +1,4 @@
+{
+  "tool_id": "__TOOL_ID__",
+  "type": "go"
+}

package/templates/executa/go/go.mod

@@ -0,0 +1,3 @@
+module __TOOL_ID__
+
+go 1.21

package/templates/executa/go/main.go

@@ -0,0 +1,148 @@
+// Minimal stdio Executa plugin scaffold (Go).
+//
+// Speaks Executa JSON-RPC 2.0 over stdin/stdout. Implements the v2
+// `initialize` handshake declaring sampling capability.
+//
+// Build & run:
+//
+//	anna-app executa dev --describe
+package main
+
+import (
+	"bufio"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"sync"
+)
+
+type envelope struct {
+	Jsonrpc string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id,omitempty"`
+	Method  string          `json:"method,omitempty"`
+	Params  json.RawMessage `json:"params,omitempty"`
+	Result  json.RawMessage `json:"result,omitempty"`
+	Error   *rpcError       `json:"error,omitempty"`
+}
+
+type rpcError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+var (
+	manifest = map[string]any{
+		"name":              "__TOOL_ID__",
+		"display_name":      "__TOOL_ID__",
+		"version":           "0.1.0",
+		"description":       "A minimal Go Executa plugin scaffold.",
+		"host_capabilities": []string{"llm.sample"},
+		"tools": []any{
+			map[string]any{
+				"name":        "ping",
+				"description": "Smoke-test method.",
+				"parameters":  []any{},
+			},
+		},
+	}
+
+	writeMu sync.Mutex
+	pending = struct {
+		sync.Mutex
+		m map[string]chan envelope
+	}{m: map[string]chan envelope{}}
+)
+
+func writeEnv(e envelope) {
+	writeMu.Lock()
+	defer writeMu.Unlock()
+	b, _ := json.Marshal(e)
+	fmt.Fprintln(os.Stdout, string(b))
+}
+
+func newID() string {
+	b := make([]byte, 8)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+func invoke(method string, args map[string]any) map[string]any {
+	switch method {
+	case "ping":
+		return map[string]any{"success": true, "data": map[string]any{"pong": true}}
+	default:
+		return map[string]any{"success": false, "error": "unknown method: " + method}
+	}
+}
+
+func dispatch(e envelope) {
+	id := e.ID
+	var result any
+	var err error
+	switch e.Method {
+	case "initialize":
+		result = map[string]any{
+			"protocolVersion": "2.0",
+			"server_info":     map[string]any{"name": manifest["name"], "version": manifest["version"]},
+			"capabilities":    map[string]any{"sampling": map[string]any{}},
+		}
+	case "describe":
+		result = manifest
+	case "health":
+		result = map[string]any{"status": "ok"}
+	case "invoke":
+		var p struct {
+			Tool      string         `json:"tool"`
+			Arguments map[string]any `json:"arguments"`
+		}
+		_ = json.Unmarshal(e.Params, &p)
+		if p.Arguments == nil {
+			p.Arguments = map[string]any{}
+		}
+		result = invoke(p.Tool, p.Arguments)
+	default:
+		err = fmt.Errorf("unknown rpc: %s", e.Method)
+	}
+	out := envelope{Jsonrpc: "2.0", ID: id}
+	if err != nil {
+		out.Error = &rpcError{Code: -32601, Message: err.Error()}
+	} else {
+		raw, _ := json.Marshal(result)
+		out.Result = raw
+	}
+	writeEnv(out)
+}
+
+func main() {
+	scanner := bufio.NewScanner(os.Stdin)
+	scanner.Buffer(make([]byte, 1<<20), 1<<24)
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		var e envelope
+		if err := json.Unmarshal(line, &e); err != nil {
+			fmt.Fprintln(os.Stderr, "bad json:", err)
+			continue
+		}
+		// Response to one of our reverse RPCs?
+		if e.Method == "" && len(e.ID) > 0 {
+			var key string
+			_ = json.Unmarshal(e.ID, &key)
+			pending.Lock()
+			ch, ok := pending.m[key]
+			if ok {
+				delete(pending.m, key)
+			}
+			pending.Unlock()
+			if ok {
+				ch <- e
+			}
+			continue
+		}
+		go dispatch(e)
+	}
+}

package/templates/executa/node/README.md

@@ -0,0 +1,12 @@
+# __SLUG__
+
+A standalone Node.js Executa plugin scaffolded by `anna-app executa init`.
+
+## Develop locally
+
+```sh
+anna-app executa dev --describe
+anna-app executa dev --invoke ping
+anna-app executa dev --mock-sampling ./sampling-fixture.jsonl \
+  --invoke summarize --args '{"text":"…"}'
+```

package/templates/executa/node/executa.json

@@ -0,0 +1,4 @@
+{
+  "tool_id": "__TOOL_ID__",
+  "type": "node"
+}

package/templates/executa/node/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "__TOOL_ID__",
+  "version": "0.1.0",
+  "description": "Executa plugin: __SLUG__",
+  "type": "module",
+  "bin": {
+    "__TOOL_ID__": "./plugin.mjs"
+  },
+  "executa": {
+    "tool_id": "__TOOL_ID__"
+  }
+}

package/templates/executa/node/plugin.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Minimal stdio Executa plugin scaffold (Node.js).
+ *
+ * Reads one JSON-RPC envelope per line on stdin, writes responses on
+ * stdout. Implements the v2 `initialize` handshake declaring sampling
+ * capability so the host can forward reverse-RPC calls.
+ */
+
+import { createInterface } from "node:readline";
+import { randomUUID } from "node:crypto";
+import process from "node:process";
+
+const MANIFEST = {
+  name: "__TOOL_ID__",
+  display_name: "__TOOL_ID__",
+  version: "0.1.0",
+  description: "A minimal Node.js Executa plugin scaffold.",
+  host_capabilities: ["llm.sample"],
+  tools: [
+    {
+      name: "ping",
+      description: "Smoke-test method.",
+      parameters: [],
+    },
+    {
+      name: "summarize",
+      description: "Summarize text via host sampling.",
+      parameters: [
+        { name: "text", type: "string", description: "Text to summarize.", required: true },
+      ],
+    },
+  ],
+};
+
+const pending = new Map(); // reverse-RPC id -> {resolve, reject}
+
+function write(env) {
+  process.stdout.write(`${JSON.stringify(env)}\n`);
+}
+
+function requestSampling(prompt) {
+  return new Promise((resolve, reject) => {
+    const id = randomUUID();
+    pending.set(id, { resolve, reject });
+    write({
+      jsonrpc: "2.0",
+      id,
+      method: "sampling/createMessage",
+      params: {
+        messages: [{ role: "user", content: { type: "text", text: prompt } }],
+        maxTokens: 400,
+      },
+    });
+  });
+}
+
+async function invoke(method, args) {
+  if (method === "ping") return { success: true, data: { pong: true } };
+  if (method === "summarize") {
+    const text = args?.text;
+    if (!text) return { success: false, error: "text is required" };
+    try {
+      const out = await requestSampling(`Summarize in one sentence:\n${text}`);
+      return { success: true, data: { summary: out?.content?.text ?? "" } };
+    } catch (e) {
+      return { success: false, error: `sampling failed: ${e.message}` };
+    }
+  }
+  return { success: false, error: `unknown method: ${method}` };
+}
+
+async function dispatch(env) {
+  const { method, id, params = {} } = env;
+  try {
+    let result;
+    if (method === "initialize") {
+      result = {
+        protocolVersion: "2.0",
+        server_info: { name: MANIFEST.name, version: MANIFEST.version },
+        capabilities: { sampling: {} },
+      };
+    } else if (method === "describe") {
+      result = MANIFEST;
+    } else if (method === "health") {
+      result = { status: "ok" };
+    } else if (method === "invoke") {
+      result = await invoke(params.tool, params.arguments ?? {});
+    } else {
+      throw Object.assign(new Error(`unknown rpc: ${method}`), { code: -32601 });
+    }
+    write({ jsonrpc: "2.0", id, result });
+  } catch (e) {
+    write({
+      jsonrpc: "2.0",
+      id,
+      error: { code: e.code ?? -32000, message: e.message },
+    });
+  }
+}
+
+function handleLine(line) {
+  const env = JSON.parse(line);
+  // Response to one of our reverse-RPC requests?
+  if (env.method == null && pending.has(env.id)) {
+    const { resolve, reject } = pending.get(env.id);
+    pending.delete(env.id);
+    if (env.error) reject(new Error(env.error.message));
+    else resolve(env.result);
+    return;
+  }
+  // Host → plugin request.
+  if (env.method) {
+    void dispatch(env);
+  }
+}
+
+createInterface({ input: process.stdin }).on("line", (raw) => {
+  const line = raw.trim();
+  if (!line) return;
+  try {
+    handleLine(line);
+  } catch (e) {
+    process.stderr.write(`bad json: ${e.message}\n`);
+  }
+});

package/templates/executa/node/sampling-fixture.jsonl

@@ -0,0 +1 @@
+{"ns":"sampling","method":"createMessage","result":{"role":"assistant","content":{"type":"text","text":"(mock) a one-line summary"},"model":"mock-model","stopReason":"endTurn"}}

package/templates/executa/python/README.md

@@ -0,0 +1,23 @@
+# __SLUG__
+
+A standalone Executa plugin scaffolded by `anna-app executa init`.
+
+## Develop locally
+
+```sh
+# Smoke-test (no LLM):
+anna-app executa dev --describe
+anna-app executa dev --invoke ping
+
+# With host sampling against a mock fixture:
+anna-app executa dev \
+  --mock-sampling ./sampling-fixture.jsonl \
+  --invoke summarize --args '{"text":"Anna is a multi-app workspace."}'
+
+# With real nexus sampling (after `anna-app login --host <nexus>`):
+anna-app executa dev \
+  --app-slug my-app \
+  --invoke summarize --args '{"text":"…"}'
+```
+
+See `__SLUG_PY___plugin.py` for the JSON-RPC protocol.