@aarmos/cli 0.1.3 → 0.2.1

package/dist/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command as Command6 } from "commander";
+import { Command as Command9 } from "commander";
 
 // src/commands/init.ts
 import { Command } from "commander";
-import { mkdirSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, statSync, cpSync, mkdtempSync, rmSync } from "fs";
+import { join, dirname, relative } from "path";
+import { tmpdir } from "os";
+import { spawnSync } from "child_process";
 
 // src/lib/keys.ts
 import { generateKeyPairSync } from "crypto";
@@ -53,13 +55,28 @@ var GITIGNORE_TEMPLATE = `# Aarmos local state
 .aarmos/keys/
 .aarmos/avar/
 `;
+var IMPORT_ALLOWLIST = [
+  "policy.aarmos.toml",
+  "avar.config.json",
+  "asp.yaml",
+  "asp.yml",
+  "policies",
+  "playbooks",
+  ".aarmos/packs"
+];
 function initCommand() {
-  return new Command("init").description("Scaffold policy.aarmos.toml, avar.config.json, and local signing key").option("--force", "Overwrite existing files", false).action(async (opts) => {
+  return new Command("init").description("Scaffold policy.aarmos.toml, avar.config.json, and local signing key").option("--force", "Overwrite existing files", false).option(
+    "--from <repo>",
+    "Seed policies/playbooks from a GitHub repo (owner/repo[#ref][/subdir]) or tarball URL. Only Aarmos config files are copied; source code and keys are never imported."
+  ).action(async (opts) => {
     const cwd = process.cwd();
     const keyDir = join(cwd, ".aarmos", "keys");
     const chainDir = join(cwd, ".aarmos", "avar");
     mkdirSync(keyDir, { recursive: true });
     mkdirSync(chainDir, { recursive: true });
+    if (opts.from) {
+      await seedFromRepo(opts.from, cwd, opts.force);
+    }
     writeIfMissing(join(cwd, "policy.aarmos.toml"), POLICY_TEMPLATE, opts.force);
     writeIfMissing(join(cwd, "avar.config.json"), AVAR_CONFIG_TEMPLATE, opts.force);
     const gitignorePath = join(cwd, ".aarmos", ".gitignore");
@@ -78,16 +95,111 @@ function writeIfMissing(path, content, force) {
     console.log(`\xB7 skipped (exists): ${path}`);
     return;
   }
+  mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, content);
   console.log(`\u2713 wrote: ${path}`);
 }
+function parseFrom(from) {
+  if (from.startsWith("http://") || from.startsWith("https://")) {
+    return { tarballUrl: from, subdir: "", label: from };
+  }
+  const hashIdx = from.indexOf("#");
+  const [pathPart, refPart] = hashIdx >= 0 ? [from.slice(0, hashIdx), from.slice(hashIdx + 1)] : [from, "main"];
+  const segs = pathPart.split("/").filter(Boolean);
+  if (segs.length < 2) throw new Error(`--from: expected owner/repo, got "${from}"`);
+  const [owner, repo, ...rest] = segs;
+  const subdir = rest.join("/");
+  return {
+    tarballUrl: `https://codeload.github.com/${owner}/${repo}/tar.gz/refs/heads/${refPart}`,
+    subdir,
+    label: `${owner}/${repo}${refPart !== "main" ? `#${refPart}` : ""}${subdir ? `/${subdir}` : ""}`
+  };
+}
+async function seedFromRepo(from, cwd, force) {
+  const parsed = parseFrom(from);
+  console.log(`\u25B8 seeding from ${parsed.label}`);
+  const staging = mkdtempSync(join(tmpdir(), "aarmos-init-"));
+  try {
+    const res = await fetch(parsed.tarballUrl);
+    if (!res.ok) throw new Error(`fetch ${parsed.tarballUrl}: ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const tarPath = join(staging, "src.tar.gz");
+    writeFileSync(tarPath, buf);
+    const extractDir = join(staging, "extract");
+    mkdirSync(extractDir);
+    const tar = spawnSync("tar", ["-xzf", tarPath, "-C", extractDir, "--strip-components=1"], {
+      stdio: ["ignore", "inherit", "inherit"]
+    });
+    if (tar.status !== 0) throw new Error("tar extract failed (is `tar` on PATH?)");
+    const root = parsed.subdir ? join(extractDir, parsed.subdir) : extractDir;
+    if (!existsSync(root)) throw new Error(`subdir not found in repo: ${parsed.subdir}`);
+    let copied = 0;
+    for (const rel of IMPORT_ALLOWLIST) {
+      const src = join(root, rel);
+      if (!existsSync(src)) continue;
+      const dest = join(cwd, rel);
+      if (existsSync(dest) && !force) {
+        console.log(`\xB7 skipped (exists): ${rel}  \u2014 pass --force to overwrite`);
+        continue;
+      }
+      if (statSync(src).isDirectory()) {
+        const violations = findKeyLikeFiles(src);
+        if (violations.length > 0) {
+          console.log(`\u2717 refusing to copy ${rel}: contains key-like files: ${violations.slice(0, 3).join(", ")}`);
+          continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        cpSync(src, dest, { recursive: true, force });
+      } else {
+        mkdirSync(dirname(dest), { recursive: true });
+        cpSync(src, dest, { force });
+      }
+      console.log(`\u2713 imported: ${rel}`);
+      copied++;
+    }
+    if (copied === 0) {
+      console.log("\xB7 no Aarmos config artifacts found in that repo; falling back to defaults");
+    }
+  } finally {
+    try {
+      rmSync(staging, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
+function findKeyLikeFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const name of readdirSync(d)) {
+      const full = join(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (/\.(key|pem|p12|pfx)$/i.test(name) || /signing\.key$/i.test(name)) {
+        out.push(relative(dir, full));
+        continue;
+      }
+      if (st.size < 32e3) {
+        try {
+          const head = readFileSync(full, "utf8").slice(0, 200);
+          if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(head)) out.push(relative(dir, full));
+        } catch {
+        }
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
 
 // src/commands/run.ts
 import { Command as Command2 } from "commander";
 import { spawn } from "child_process";
 
 // src/lib/avar.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync } from "fs";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
 import { createHash } from "crypto";
 var CHAIN_DIR = ".aarmos/avar";
@@ -131,10 +243,10 @@ function serialize(receipt) {
 }
 
 // src/lib/policy.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
 import { createHash as createHash2 } from "crypto";
 function loadPolicy(path) {
-  const raw = existsSync3(path) ? readFileSync2(path, "utf8") : "";
+  const raw = existsSync3(path) ? readFileSync3(path, "utf8") : "";
   const digest = createHash2("sha256").update(raw).digest("hex");
   return { path, raw, digest };
 }
@@ -242,7 +354,7 @@ function stripHopByHop(headers) {
 
 // src/commands/daemon.ts
 import { Command as Command4 } from "commander";
-import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync3, unlinkSync, mkdirSync as mkdirSync3 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3, unlinkSync, mkdirSync as mkdirSync3 } from "fs";
 import { join as join3 } from "path";
 import { spawn as spawn2 } from "child_process";
 var PID_FILE = join3(process.cwd(), ".aarmos", "daemon.pid");
@@ -267,7 +379,7 @@ function daemonCommand() {
       console.log("\xB7 no daemon running");
       return;
     }
-    const pid = Number(readFileSync3(PID_FILE, "utf8"));
+    const pid = Number(readFileSync4(PID_FILE, "utf8"));
     try {
       process.kill(pid);
     } catch {
@@ -280,14 +392,14 @@ function daemonCommand() {
       console.log("stopped");
       return;
     }
-    const pid = Number(readFileSync3(PID_FILE, "utf8"));
+    const pid = Number(readFileSync4(PID_FILE, "utf8"));
     console.log(`running (pid ${pid})`);
   });
   return cmd;
 }
 function isRunning() {
   if (!existsSync4(PID_FILE)) return false;
-  const pid = Number(readFileSync3(PID_FILE, "utf8"));
+  const pid = Number(readFileSync4(PID_FILE, "utf8"));
   try {
     process.kill(pid, 0);
     return true;
@@ -298,7 +410,7 @@ function isRunning() {
 
 // src/commands/verify.ts
 import { Command as Command5 } from "commander";
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { unzipSync, strFromU8 } from "fflate";
 
 // ../avar-core/src/canonicalize.ts
@@ -401,8 +513,8 @@ function getSubtle2() {
   return c.subtle;
 }
 function b64uDecode(s) {
-  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
-  const bin = typeof atob === "function" ? atob(b64) : globalThis.Buffer.from(b64, "base64").toString("binary");
+  const b642 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+  const bin = typeof atob === "function" ? atob(b642) : globalThis.Buffer.from(b642, "base64").toString("binary");
   const out = new Uint8Array(bin.length);
   for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
   return out;
@@ -597,15 +709,155 @@ function computeChainHead(entries) {
   return { entryHash: "", index: -1 };
 }
 
+// ../avar-core/src/errors.ts
+var SPEC_URL = "https://aarmos.io/docs/avar-spec";
+var VERIFY_URL = "https://aarmos.io/trust/verify";
+var QUICKSTART_URL = "https://aarmos.io/docs/quickstart";
+var AARMOS_ERROR_TEMPLATES = {
+  BUNDLE_OVERSIZED: {
+    message: "That bundle is larger than the 25 MB browser limit.",
+    hint: "Run `aarmos verify <bundle>` locally instead \u2014 the CLI has no size cap.",
+    docsUrl: QUICKSTART_URL
+  },
+  BUNDLE_NOT_ZIP: {
+    message: "That file is not a valid .avar.zip.",
+    hint: "Bundles are zip archives. Rename or re-export the file, then try again.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_MISSING_FILES: {
+    message: "Bundle is missing one or more required files.",
+    hint: "A valid AVAR bundle contains SPEC-VERSION, manifest.json, entries.ndjson, and pubkeys.json.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_JSON: {
+    message: "manifest.json or pubkeys.json is not valid JSON.",
+    hint: "The file exists but cannot be parsed. Re-export from the CLI to regenerate a clean bundle.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_INVALID_NDJSON: {
+    message: "entries.ndjson contains a malformed line.",
+    hint: "Each line must be a self-contained JSON entry. One corrupt line usually means the file was edited by hand.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_SPEC_UNSUPPORTED: {
+    message: "This bundle was produced by a spec version this verifier does not support.",
+    hint: "Update to the latest verifier (`npm i -g @aarmos/avar-core`) or re-export with a matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  BUNDLE_EMPTY: {
+    message: "Bundle contains no entries.",
+    hint: "An empty ledger is unusual \u2014 check that the run actually produced receipts before exporting.",
+    docsUrl: SPEC_URL
+  },
+  SPEC_VERSION_MISMATCH: {
+    message: "This bundle uses a spec version this verifier does not recognize.",
+    hint: "Update the verifier (`npm i -g @aarmos/avar-core`) or re-export the bundle with matching spec version.",
+    docsUrl: SPEC_URL
+  },
+  ENTRIES_SHA256_MISMATCH: {
+    message: "entries.ndjson has been modified since the bundle was signed.",
+    hint: "The envelope hash in manifest.json no longer matches the file. Do not trust this bundle \u2014 re-export from the CLI.",
+    docsUrl: VERIFY_URL
+  },
+  SIGNATURE_MISMATCH: {
+    message: "One or more entry signatures do not match the embedded public keys.",
+    hint: "The bundle was modified after signing, or the wrong pubkeys.json is bundled.",
+    docsUrl: VERIFY_URL
+  },
+  FINGERPRINT_MISMATCH: {
+    message: "Device fingerprint on one or more entries does not match its public key.",
+    hint: "The entry claims a device whose public key does not hash to the declared fingerprint. Treat this bundle as untrusted.",
+    docsUrl: VERIFY_URL
+  },
+  CHAIN_BROKEN: {
+    message: "The per-entry hash chain is broken.",
+    hint: "An entry was inserted, removed, or edited after signing. The break index is shown in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  STEP_CHAIN_BROKEN: {
+    message: "The per-step hash chain inside one or more entries is broken.",
+    hint: "A decision or tool step was tampered with. The affected entry index is in the issues list.",
+    docsUrl: VERIFY_URL
+  },
+  MANIFEST_INVALID: {
+    message: "manifest.json is missing required fields or uses an unsupported format.",
+    hint: "Re-export the bundle from the CLI \u2014 do not edit manifest.json by hand.",
+    docsUrl: SPEC_URL
+  },
+  FILE_NOT_FOUND: {
+    message: "Receipt not found at the given path.",
+    hint: "Check the path \u2014 a common cause is running from a different working directory than expected.",
+    docsUrl: QUICKSTART_URL
+  },
+  FILE_UNREADABLE: {
+    message: "Receipt exists but could not be read.",
+    hint: "Check filesystem permissions on the file.",
+    docsUrl: QUICKSTART_URL
+  },
+  UNKNOWN: {
+    message: "Something went wrong while verifying that bundle.",
+    hint: "Try again with a fresh export. If the error persists, run `aarmos verify` locally to see the raw error.",
+    docsUrl: QUICKSTART_URL
+  }
+};
+function aarmosError(code, overrides = {}) {
+  const base = AARMOS_ERROR_TEMPLATES[code];
+  return {
+    code,
+    message: overrides.message ?? base.message,
+    hint: overrides.hint ?? base.hint,
+    docsUrl: overrides.docsUrl ?? base.docsUrl
+  };
+}
+function formatAarmosErrorLine(err) {
+  return `\u2717 ${err.code}: ${err.message}
+  Next: ${err.hint}
+  Docs: ${err.docsUrl}`;
+}
+function classifyReport(report) {
+  if (report.verdict !== "invalid") return null;
+  if (!report.entriesSha256Ok) return aarmosError("ENTRIES_SHA256_MISMATCH");
+  if (!report.signaturesOk) return aarmosError("SIGNATURE_MISMATCH");
+  if (!report.fingerprintsOk) return aarmosError("FINGERPRINT_MISMATCH");
+  if (!report.chainOk) return aarmosError("CHAIN_BROKEN");
+  if (!report.perStepChainOk) return aarmosError("STEP_CHAIN_BROKEN");
+  if (!report.formatOk) {
+    const specIssue = report.issues.find((i) => i.kind === "spec-version-mismatch");
+    if (specIssue) {
+      return aarmosError("SPEC_VERSION_MISMATCH", {
+        message: specIssue.detail ? `Spec mismatch \u2014 ${specIssue.detail}` : void 0
+      });
+    }
+    return aarmosError("MANIFEST_INVALID");
+  }
+  return aarmosError("UNKNOWN");
+}
+
 // src/commands/verify.ts
 async function runVerify(opts) {
   const { file, json = false, quiet = false } = opts;
+  const emitError = (err, rc) => {
+    if (json) {
+      process.stdout.write(JSON.stringify({ verdict: "invalid", error: err }) + "\n");
+    } else if (!quiet) {
+      process.stderr.write(formatAarmosErrorLine(err) + "\n");
+    }
+    return rc;
+  };
   if (!existsSync5(file)) {
-    if (!quiet) process.stderr.write(`\u2717 receipt not found: ${file}
-`);
-    return 2;
+    return emitError(aarmosError("FILE_NOT_FOUND", { message: `Receipt not found: ${file}` }), 2);
+  }
+  let bytes;
+  try {
+    bytes = readFileSync5(file);
+  } catch (err) {
+    return emitError(
+      aarmosError("FILE_UNREADABLE", {
+        message: err instanceof Error ? err.message : String(err)
+      }),
+      1
+    );
   }
-  const bytes = readFileSync4(file);
   const isZip = looksLikeZip(bytes);
   if (!isZip) {
     try {
@@ -633,23 +885,40 @@ async function runVerify(opts) {
       }
       return 0;
     } catch (err) {
-      if (!quiet) process.stderr.write(`\u2717 invalid JSON: ${String(err)}
-`);
-      return 1;
+      return emitError(
+        aarmosError("BUNDLE_INVALID_JSON", {
+          message: `invalid JSON receipt: ${err instanceof Error ? err.message : String(err)}`
+        }),
+        1
+      );
     }
   }
   let bundle;
   try {
     bundle = parseBundleBytes(bytes);
   } catch (err) {
-    if (!quiet) process.stderr.write(`\u2717 malformed .avar.zip: ${String(err)}
-`);
-    return 1;
+    const raw = err instanceof Error ? err.message : String(err);
+    let classified2;
+    if (/missing /i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_MISSING_FILES", { message: raw });
+    } else if (/invalid zip|central directory|not a zip/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_NOT_ZIP", { message: raw });
+    } else if (/ndjson|entries\.ndjson/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_INVALID_NDJSON", { message: raw });
+    } else if (/JSON|Unexpected token/i.test(raw)) {
+      classified2 = aarmosError("BUNDLE_INVALID_JSON", { message: raw });
+    } else {
+      classified2 = aarmosError("UNKNOWN", { message: `malformed .avar.zip: ${raw}` });
+    }
+    return emitError(classified2, 1);
   }
   const report = await verifyBundle(bundle);
   const failed = report.verdict === "invalid";
+  const classified = classifyReport(report);
   if (json) {
-    process.stdout.write(JSON.stringify(report) + "\n");
+    process.stdout.write(
+      JSON.stringify(classified ? { ...report, error: classified } : report) + "\n"
+    );
   } else if (!quiet) {
     const mark = failed ? "\u2717" : "\u2713";
     process.stdout.write(`${mark} verdict: ${report.verdict}
@@ -666,11 +935,15 @@ async function runVerify(opts) {
       process.stdout.write(`  issues:
 `);
       for (const issue of report.issues) {
-        process.stdout.write(`    - [${issue.kind}] ${issue.detail}
+        process.stdout.write(`    - [${issue.kind}] ${issue.detail ?? ""}
 `);
       }
     }
-    process.stdout.write("\nverified locally \u2014 no Aarmos service was contacted.\n");
+    if (classified) {
+      process.stderr.write("\n" + formatAarmosErrorLine(classified) + "\n");
+    } else {
+      process.stdout.write("\nverified locally \u2014 no Aarmos service was contacted.\n");
+    }
   }
   return failed ? 1 : 0;
 }
@@ -700,8 +973,444 @@ function verifyCommand() {
   });
 }
 
+// src/commands/lint.ts
+import { Command as Command6 } from "commander";
+import { existsSync as existsSync6, readFileSync as readFileSync6, statSync as statSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join4, extname } from "path";
+
+// src/lib/asp-compile.ts
+import { parse as parseYaml } from "yaml";
+import { createHash as createHash3, createPrivateKey, sign as edSign, generateKeyPairSync as generateKeyPairSync2 } from "crypto";
+function canonicalize2(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return "[" + value.map(canonicalize2).join(",") + "]";
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize2(obj[k])).join(",") + "}";
+}
+function parseAspYaml(source) {
+  const doc = parseYaml(source);
+  if (!doc || typeof doc !== "object") throw new Error("ASP YAML must be a mapping");
+  return doc;
+}
+function compileAsp(doc) {
+  const errors = [];
+  const v = doc.version ?? 1;
+  if (v !== 1) errors.push(`version must be 1 (got ${v})`);
+  const name = doc.metadata?.issuer?.name;
+  const pubKey = doc.metadata?.issuer?.pubKey;
+  if (!name) errors.push("metadata.issuer.name is required");
+  if (!pubKey) errors.push("metadata.issuer.pubKey is required (base64 raw 32B ed25519)");
+  const issuedAt = doc.metadata?.issuedAt;
+  const expiresAt = doc.metadata?.expiresAt;
+  if (!issuedAt) errors.push("metadata.issuedAt is required (ISO 8601)");
+  if (!expiresAt) errors.push("metadata.expiresAt is required (ISO 8601)");
+  if (issuedAt && Number.isNaN(Date.parse(issuedAt)))
+    errors.push(`metadata.issuedAt is not a valid ISO date: ${issuedAt}`);
+  if (expiresAt && Number.isNaN(Date.parse(expiresAt)))
+    errors.push(`metadata.expiresAt is not a valid ISO date: ${expiresAt}`);
+  if (issuedAt && expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt))
+    errors.push("metadata.expiresAt must be after metadata.issuedAt");
+  if (errors.length) return { ok: false, errors };
+  const policy = {};
+  if (doc.allow?.servers?.length) policy.allowedServers = [...doc.allow.servers];
+  if (doc.allow?.tools?.length) policy.allowedTools = [...doc.allow.tools];
+  if (doc.deny?.tools?.length) policy.deniedTools = [...doc.deny.tools];
+  if (doc.scopes && Object.keys(doc.scopes).length) policy.allowedScopes = { ...doc.scopes };
+  if (typeof doc.kill_switch?.default === "boolean")
+    policy.killSwitchDefault = doc.kill_switch.default;
+  if (doc.redaction?.length) policy.redactionRules = doc.redaction.map((r) => ({ ...r }));
+  if (doc.autonomous_scopes?.length)
+    policy.autonomousScopes = doc.autonomous_scopes.map((s) => ({
+      agentId: s.agent_id,
+      tools: [...s.tools],
+      maxUsdPerDay: s.max_usd_per_day,
+      maxStepsPerRun: s.max_steps_per_run,
+      expiresAt: s.expires_at
+    }));
+  const body = {
+    version: 1,
+    issuer: { name, pubKey },
+    issuedAt,
+    expiresAt,
+    policy
+  };
+  return { ok: true, body, canonical: canonicalize2(body) };
+}
+function compileAspYamlToCanonicalJson(source) {
+  let doc;
+  try {
+    doc = parseAspYaml(source);
+  } catch (err) {
+    return { ok: false, errors: [`YAML parse error: ${err.message}`] };
+  }
+  return compileAsp(doc);
+}
+var fromB64u = (s) => {
+  const pad = s.length % 4 === 0 ? "" : "=".repeat(4 - s.length % 4);
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64");
+};
+var b64 = (buf) => Buffer.from(buf).toString("base64");
+function privateKeyFromSeedB64u(seedB64u) {
+  const seed = fromB64u(seedB64u);
+  if (seed.length !== 32) throw new Error("Seed must be 32 bytes (base64url)");
+  const pkcs8 = Buffer.concat([Buffer.from("302e020100300506032b657004220420", "hex"), seed]);
+  return createPrivateKey({ key: pkcs8, format: "der", type: "pkcs8" });
+}
+function signBody(body, seedB64u) {
+  const priv = privateKeyFromSeedB64u(seedB64u);
+  const canon = canonicalize2(body);
+  const sig = edSign(null, Buffer.from(canon), priv);
+  return { ...body, sig: b64(sig) };
+}
+function keygen() {
+  const { publicKey, privateKey } = generateKeyPairSync2("ed25519");
+  const pubJwk = publicKey.export({ format: "jwk" });
+  const privJwk = privateKey.export({ format: "jwk" });
+  return { pubKeyB64: b64(fromB64u(pubJwk.x)), seedB64u: privJwk.d };
+}
+
+// src/commands/lint.ts
+function collectFiles(target) {
+  if (!existsSync6(target)) return [];
+  const st = statSync2(target);
+  if (st.isFile()) return [target];
+  const out = [];
+  for (const name of readdirSync2(target)) {
+    const full = join4(target, name);
+    const s = statSync2(full);
+    if (s.isDirectory()) {
+      if (name === "tests" || name === "node_modules" || name.startsWith(".")) continue;
+      out.push(...collectFiles(full));
+    } else if (extname(name) === ".yaml" || extname(name) === ".yml") {
+      if (name.endsWith(".asp.yaml") || name === "asp.yaml" || name === "asp.yml") {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+function lintPath(target) {
+  const files = collectFiles(target);
+  const issues = [];
+  if (files.length === 0) {
+    issues.push({ severity: "error", file: target, message: "no ASP files found (asp.yaml or *.asp.yaml)" });
+    return issues;
+  }
+  for (const file of files) {
+    const src = readFileSync6(file, "utf8");
+    const result = compileAspYamlToCanonicalJson(src);
+    if (!result.ok) {
+      for (const m of result.errors) issues.push({ severity: "error", file, message: m });
+      continue;
+    }
+    const body = result.body;
+    const dangerous = /(delete|drop|admin|payment|transfer)/i;
+    const allow = body.policy.allowedTools ?? [];
+    const hasDangerous = allow.some((t) => dangerous.test(t));
+    if (hasDangerous) {
+      issues.push({
+        severity: "warning",
+        file,
+        message: "allow.tools includes admin/delete-capable patterns \u2014 declare human_oversight.require_approval_for or move to deny."
+      });
+    }
+    const deny = body.policy.deniedTools ?? [];
+    for (const d of deny) {
+      if (allow.includes(d)) {
+        issues.push({ severity: "warning", file, message: `rule "${d}" is in both allow.tools and deny.tools (deny wins; remove from allow).` });
+      }
+    }
+    const soon = Date.parse(body.expiresAt) - Date.now() < 7 * 24 * 3600 * 1e3;
+    if (soon) {
+      issues.push({ severity: "warning", file, message: `metadata.expiresAt is within 7 days (${body.expiresAt}).` });
+    }
+  }
+  return issues;
+}
+function lintCommand() {
+  return new Command6("lint").description("Validate ASP YAML policy files. Zero network.").argument("[path]", "File or directory to lint", ".").option("--strict", "Treat warnings as errors").option("--json", "Emit JSON report").action((path, opts) => {
+    const issues = lintPath(path);
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ errors, warnings }, null, 2) + "\n");
+    } else {
+      for (const i of issues) {
+        const mark = i.severity === "error" ? "\u2717" : "\u26A0";
+        process.stdout.write(`${mark} [${i.severity}] ${i.file}: ${i.message}
+`);
+      }
+      if (errors.length === 0 && warnings.length === 0) {
+        process.stdout.write("\u2713 ASP clean.\n");
+      }
+    }
+    if (errors.length > 0) process.exit(1);
+    if (opts.strict && warnings.length > 0) process.exit(2);
+    process.exit(0);
+  });
+}
+
+// src/commands/test.ts
+import { Command as Command7 } from "commander";
+import { existsSync as existsSync7, readFileSync as readFileSync7, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { join as join5, extname as extname2, dirname as dirname2 } from "path";
+import { parse as parseYaml2 } from "yaml";
+
+// src/lib/asp-eval.ts
+function globMatch(pattern, value) {
+  const re = new RegExp(
+    "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
+  );
+  return re.test(value);
+}
+function evaluate(body, call) {
+  const p = body.policy;
+  if (p.deniedTools?.some((g) => globMatch(g, call.tool))) {
+    return { decision: "deny", reason: `matched deny.tools glob for "${call.tool}"` };
+  }
+  if (call.server && p.allowedServers && p.allowedServers.length > 0) {
+    const serverOk = p.allowedServers.some((s) => s === call.server || globMatch(s, call.server));
+    if (!serverOk) return { decision: "deny", reason: `server "${call.server}" not in allow.servers` };
+  }
+  if (p.allowedTools && p.allowedTools.length > 0) {
+    const toolOk = p.allowedTools.some((g) => globMatch(g, call.tool));
+    if (!toolOk) return { decision: "deny", reason: `tool "${call.tool}" not in allow.tools` };
+  }
+  if (call.scopes && p.allowedScopes) {
+    for (const [svc, requested] of Object.entries(call.scopes)) {
+      const allowed = p.allowedScopes[svc] ?? [];
+      for (const scope of requested) {
+        if (!allowed.includes(scope)) {
+          return { decision: "deny", reason: `scope "${scope}" not allowed for service "${svc}"` };
+        }
+      }
+    }
+  }
+  return { decision: "allow", reason: "matched allow rules" };
+}
+
+// src/commands/test.ts
+function findAspYaml(startDir) {
+  let d = startDir;
+  for (let i = 0; i < 6; i++) {
+    for (const cand of ["asp.yaml", "asp.yml"]) {
+      const p = join5(d, cand);
+      if (existsSync7(p)) return p;
+    }
+    const parent = dirname2(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return null;
+}
+function collectFixtures(target) {
+  if (!existsSync7(target)) return [];
+  const st = statSync3(target);
+  if (st.isFile()) return [target];
+  const out = [];
+  for (const name of readdirSync3(target)) {
+    const full = join5(target, name);
+    const s = statSync3(full);
+    if (s.isDirectory()) out.push(...collectFixtures(full));
+    else if ((extname2(name) === ".yaml" || extname2(name) === ".yml") && !name.endsWith(".asp.yaml"))
+      out.push(full);
+  }
+  return out;
+}
+function runFixtures(target) {
+  const dir = existsSync7(target) && statSync3(target).isDirectory() ? target : "policies/tests";
+  const fixtures = collectFixtures(existsSync7(dir) ? dir : target);
+  const results = [];
+  for (const file of fixtures) {
+    let fx;
+    try {
+      fx = parseYaml2(readFileSync7(file, "utf8"));
+    } catch (err) {
+      results.push({ file, name: "<parse>", ok: false, reason: err.message });
+      continue;
+    }
+    const policyPath = fx.policy ? join5(dirname2(file), fx.policy) : findAspYaml(dirname2(file));
+    if (!policyPath || !existsSync7(policyPath)) {
+      results.push({ file, name: "<policy>", ok: false, reason: "no asp.yaml found" });
+      continue;
+    }
+    const compiled = compileAspYamlToCanonicalJson(readFileSync7(policyPath, "utf8"));
+    if (!compiled.ok) {
+      results.push({ file, name: "<compile>", ok: false, reason: compiled.errors.join("; ") });
+      continue;
+    }
+    for (const c of fx.cases ?? []) {
+      const r = evaluate(compiled.body, c.call);
+      const ok = r.decision === c.expect;
+      results.push({
+        file,
+        name: c.name,
+        ok,
+        reason: ok ? r.reason : `expected ${c.expect}, got ${r.decision} (${r.reason})`
+      });
+    }
+  }
+  return results;
+}
+function testCommand() {
+  return new Command7("test").description("Run ASP policy golden tests against fixtures. Deterministic, zero network.").argument("[path]", "Fixtures dir", "policies/tests").option("--json", "Emit JSON report").action((path, opts) => {
+    const results = runFixtures(path);
+    const failed = results.filter((r) => !r.ok);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({ results }, null, 2) + "\n");
+    } else {
+      for (const r of results) {
+        process.stdout.write(`${r.ok ? "\u2713" : "\u2717"} ${r.file} :: ${r.name} \u2014 ${r.reason}
+`);
+      }
+      process.stdout.write(`
+${results.length - failed.length}/${results.length} passed.
+`);
+    }
+    process.exit(failed.length > 0 ? 1 : 0);
+  });
+}
+
+// src/commands/policy.ts
+import { Command as Command8 } from "commander";
+import { existsSync as existsSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync4, watch as fsWatch, statSync as statSync4 } from "fs";
+import { dirname as dirname3, resolve } from "path";
+function readAspOrDie(path) {
+  if (!existsSync8(path)) {
+    process.stderr.write(`\u2717 file not found: ${path}
+`);
+    process.exit(1);
+  }
+  return readFileSync8(path, "utf8");
+}
+function runPolicyOnce(policyPath, testsDir, opts = {}) {
+  const started = Date.now();
+  let output = `
+\u25B8 ${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${opts.label ?? policyPath}
+`;
+  const src = readFileSync8(policyPath, "utf8");
+  const compiled = compileAspYamlToCanonicalJson(src);
+  if (!compiled.ok) {
+    for (const m of compiled.errors) output += `  \u2717 compile: ${m}
+`;
+    return { ok: false, output, passed: 0, total: 0 };
+  }
+  const toolCount = (compiled.body.policy.allowedTools?.length ?? 0) + (compiled.body.policy.deniedTools?.length ?? 0);
+  output += `  \u2713 compiled  (${toolCount} tool rule[s], issuer=${compiled.body.issuer?.pubKey ?? "(unsigned)"})
+`;
+  if (!existsSync8(testsDir)) {
+    output += `  \xB7 no fixtures at ${opts.testsLabel ?? testsDir} \u2014 skipping tests
+`;
+    return { ok: true, output, passed: 0, total: 0 };
+  }
+  const results = runFixtures(testsDir);
+  const failed = results.filter((r) => !r.ok);
+  for (const r of failed) output += `  \u2717 ${r.file} :: ${r.name} \u2014 ${r.reason}
+`;
+  const passed = results.length - failed.length;
+  output += `  ${failed.length === 0 ? "\u2713" : "\u2717"} ${passed}/${results.length} passed  (${Date.now() - started}ms)
+`;
+  return { ok: failed.length === 0, output, passed, total: results.length };
+}
+function policyCommand() {
+  const cmd = new Command8("policy").description("Compile / sign ASP YAML policies.");
+  cmd.command("compile <file>").description("Compile ASP YAML \u2192 canonical JSON bundle body (unsigned).").option("--out <file>", "Write to file instead of stdout").action((file, opts) => {
+    const result = compileAspYamlToCanonicalJson(readAspOrDie(file));
+    if (!result.ok) {
+      for (const m of result.errors) process.stderr.write(`\u2717 ${m}
+`);
+      process.exit(1);
+    }
+    const out = JSON.stringify(result.body, null, 2) + "\n";
+    if (opts.out) {
+      writeFileSync4(opts.out, out);
+      process.stderr.write(`\u2713 wrote ${opts.out}
+`);
+    } else {
+      process.stdout.write(out);
+    }
+  });
+  cmd.command("sign <file>").description(
+    "Compile + Ed25519-sign ASP YAML into a policy bundle the Aarmos runtime consumes. Reads AARMOS_POLICY_PRIVATE_KEY (base64url 32B seed)."
+  ).option("--out <file>", "Write signed bundle here (default: stdout)").action((file, opts) => {
+    const seed = process.env.AARMOS_POLICY_PRIVATE_KEY;
+    if (!seed) {
+      process.stderr.write("\u2717 AARMOS_POLICY_PRIVATE_KEY not set (base64url 32B ed25519 seed)\n");
+      process.exit(1);
+    }
+    const result = compileAspYamlToCanonicalJson(readAspOrDie(file));
+    if (!result.ok) {
+      for (const m of result.errors) process.stderr.write(`\u2717 ${m}
+`);
+      process.exit(1);
+    }
+    const signed = signBody(result.body, seed);
+    const out = JSON.stringify(signed, null, 2) + "\n";
+    if (opts.out) {
+      writeFileSync4(opts.out, out);
+      process.stderr.write(`\u2713 signed \u2192 ${opts.out}
+`);
+    } else {
+      process.stdout.write(out);
+    }
+  });
+  cmd.command("keygen").description("Generate a new Ed25519 keypair for signing ASP policies.").action(() => {
+    const k = keygen();
+    process.stdout.write(
+      `issuer.pubKey (paste into metadata.issuer.pubKey):
+  ${k.pubKeyB64}
+
+AARMOS_POLICY_PRIVATE_KEY (keep secret):
+  ${k.seedB64u}
+`
+    );
+  });
+  cmd.command("watch <file>").description(
+    "Recompile ASP YAML on save and re-run fixtures. Zero network, zero side effects \u2014 the tightest feedback loop for authoring policy."
+  ).option("--tests <dir>", "Fixtures directory to re-run on each change", "policies/tests").option("--debounce <ms>", "Debounce interval in ms", "150").action((file, opts) => {
+    const policyPath = resolve(file);
+    if (!existsSync8(policyPath)) {
+      process.stderr.write(`\u2717 file not found: ${policyPath}
+`);
+      process.exit(1);
+    }
+    const testsDir = resolve(opts.tests);
+    const debounceMs = Math.max(0, Number(opts.debounce) || 150);
+    const runOnce = () => {
+      const { output } = runPolicyOnce(policyPath, testsDir, { label: file, testsLabel: opts.tests });
+      process.stdout.write(output);
+    };
+    process.stdout.write(`aarmos policy watch
+  policy : ${policyPath}
+  tests  : ${testsDir}
+`);
+    runOnce();
+    let timer = null;
+    const schedule = () => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(runOnce, debounceMs);
+    };
+    const watchTarget = (p) => {
+      try {
+        const st = statSync4(p);
+        const opts2 = st.isDirectory() ? { recursive: true } : void 0;
+        fsWatch(p, opts2, () => schedule());
+      } catch {
+      }
+    };
+    watchTarget(policyPath);
+    watchTarget(dirname3(policyPath));
+    if (existsSync8(testsDir)) watchTarget(testsDir);
+    process.stdout.write("\nwatching for changes \u2014 Ctrl+C to exit\n");
+    setInterval(() => {
+    }, 1 << 30);
+  });
+  return cmd;
+}
+
 // src/index.ts
-var program = new Command6();
+var program = new Command9();
 program.name("aarmos").description(
   "Run your agent locally, across any protocol, with a signed receipt \u2014 in 60 seconds."
 ).version("0.1.0");
@@ -710,6 +1419,9 @@ program.addCommand(runCommand());
 program.addCommand(proxyCommand());
 program.addCommand(daemonCommand());
 program.addCommand(verifyCommand());
+program.addCommand(lintCommand());
+program.addCommand(testCommand());
+program.addCommand(policyCommand());
 program.parseAsync(process.argv).catch((err) => {
   console.error(err instanceof Error ? err.message : String(err));
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarmos/cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Aarmos CLI — run any agent locally, across any protocol (MCP, OpenAPI, deep-link), with a signed AVAR receipt on every execution. Sovereign runtime, universal tool gateway, verifiable governance.",
   "keywords": [
     "aarmos",
@@ -39,6 +39,7 @@
     "@aarmos/avar-core": "^1.0.0-rc.3",
     "commander": "^12.1.0",
     "fflate": "^0.8.3",
+    "yaml": "^2.9.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {