@arkveil/cli 1.0.0 → 1.2.0

package/dist/index.js

@@ -590,15 +590,15 @@ var require_help = __commonJS({
        * @return {string}
        *
        */
-      wrap(str, width, indent, minColumnWidth = 40) {
+      wrap(str, width, indent2, minColumnWidth = 40) {
         const indents = " \\f\\t\\v\xA0\u1680\u2000-\u200A\u202F\u205F\u3000\uFEFF";
         const manualIndent = new RegExp(`[\\n][${indents}]+`);
         if (str.match(manualIndent)) return str;
-        const columnWidth = width - indent;
+        const columnWidth = width - indent2;
         if (columnWidth < minColumnWidth) return str;
-        const leadingStr = str.slice(0, indent);
-        const columnText = str.slice(indent).replace("\r\n", "\n");
-        const indentString = " ".repeat(indent);
+        const leadingStr = str.slice(0, indent2);
+        const columnText = str.slice(indent2).replace("\r\n", "\n");
+        const indentString = " ".repeat(indent2);
         const zeroWidthSpace = "\u200B";
         const breaks = `\\s${zeroWidthSpace}`;
         const regex2 = new RegExp(
@@ -5276,14 +5276,14 @@ var init_open = __esm({
       }
       const subprocess = childProcess.spawn(command, cliArguments, childProcessOptions);
       if (options.wait) {
-        return new Promise((resolve, reject) => {
+        return new Promise((resolve2, reject) => {
           subprocess.once("error", reject);
           subprocess.once("close", (exitCode) => {
             if (!options.allowNonzeroExitCode && exitCode > 0) {
               reject(new Error(`Exited with code ${exitCode}`));
               return;
             }
-            resolve(subprocess);
+            resolve2(subprocess);
           });
         });
       }
@@ -5413,9 +5413,9 @@ var require_src = __commonJS({
 });
 
 // src/index.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import { dirname, join as join2 } from "path";
+import { readFileSync as readFileSync5 } from "fs";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { dirname as dirname2, join as join3 } from "path";
 
 // node_modules/.pnpm/commander@12.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
@@ -10913,11 +10913,11 @@ var Ora = class {
   get indent() {
     return this.#indent;
   }
-  set indent(indent = 0) {
-    if (!(indent >= 0 && Number.isInteger(indent))) {
+  set indent(indent2 = 0) {
+    if (!(indent2 >= 0 && Number.isInteger(indent2))) {
       throw new Error("The `indent` option must be an integer from 0 and up");
     }
-    this.#indent = indent;
+    this.#indent = indent2;
     this.#updateLineCount();
   }
   get interval() {
@@ -11750,7 +11750,7 @@ import { randomUUID } from "crypto";
 var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var MAX_BACKOFF_MS = 5e3;
-var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 function backoffDelay(attempt, retryAfter) {
   if (retryAfter) {
     const seconds = Number(retryAfter);
@@ -12205,7 +12205,7 @@ function extractOAuthErrorDescription(json) {
   }
   return void 0;
 }
-var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var sleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 async function parseJson(response, url) {
   const text = await safeText(response);
   if (!text) return {};
@@ -13256,7 +13256,10 @@ async function setSchema(ctx, type, options) {
 var TYPE_CHOICES = ["user", "context", "action"];
 function registerSchemas(program2) {
   const schemas = program2.command("schemas").description("Manage USER/CONTEXT/ACTION attribute JSON schemas");
-  schemas.command("get").description("Show the JSON Schema for an attribute type").addArgument(new Argument("<type>", "attribute schema type").choices(TYPE_CHOICES)).action(async (type, _options, command) => {
+  schemas.command("get").description("Show the JSON Schema for an attribute type").addArgument(new Argument("<type>", "attribute schema type").choices(TYPE_CHOICES)).addHelpText(
+    "after",
+    "\nTo type the SDK from these schemas (user/context), see the recipe in\n`arkveil sdk info` \u2014 fetch with --json, generate TypeScript, and augment\nthe SDK's ArkveilUserRegistry / ArkveilContextRegistry.\n"
+  ).action(async (type, _options, command) => {
     await run(command, (ctx) => getSchema(ctx, type));
   });
   schemas.command("set").description("Replace the JSON Schema for an attribute type").addArgument(new Argument("<type>", "attribute schema type").choices(TYPE_CHOICES)).option("--data <json>", "JSON Schema: inline JSON, @file, or - for stdin").addHelpText("after", "\nExample:\n  $ arkveil schemas set user --data @user-schema.json\n").action(async (type, options, command) => {
@@ -13264,6 +13267,614 @@ function registerSchemas(program2) {
   });
 }
 
+// src/commands/sdk/catalog.ts
+var SDK_CATALOG = {
+  language: "TypeScript / JavaScript",
+  languages: ["TypeScript", "JavaScript"],
+  registry: "npm",
+  requirements: { node: ">=18", typescript: "^5 (for typed usage)" },
+  note: "Only TypeScript / JavaScript is supported today, via three packages: the core SDK (arkveil), Node.js/Express (@arkveil/node), and NestJS (@arkveil/nest). There are no SDKs for other languages yet.",
+  targets: [
+    {
+      id: "nest",
+      title: "NestJS SDK",
+      package: "@arkveil/nest",
+      platform: "NestJS (Node.js)",
+      frameworks: ["NestJS"],
+      whenToUse: "Use in a NestJS application. Configure once with ArkveilModule.forRoot and protect routes declaratively with the @PermissionPoint decorator.",
+      install: "npm install @arkveil/nest",
+      quickStart: `import { Module } from "@nestjs/common";
+import { ArkveilModule } from "@arkveil/nest";
+
+@Module({
+  imports: [
+    ArkveilModule.forRoot({
+      serviceUrl: "https://api.arkveil.com",
+      apiKey: process.env.ARKVEIL_API_KEY!,
+      getUserAttributes: (req) => ({ id: req.user?.id, role: req.user?.role }),
+    }),
+  ],
+})
+export class AppModule {}
+
+// Protect a route \u2014 the code is type-checked once the registry is augmented:
+import { Controller, Delete } from "@nestjs/common";
+import { PermissionPoint } from "@arkveil/nest";
+
+@Controller("articles")
+export class ArticlesController {
+  @Delete(":id")
+  @PermissionPoint("content-service.article-delete")
+  remove() {
+    return "Protected content";
+  }
+}`,
+      docs: "https://www.npmjs.com/package/@arkveil/nest"
+    },
+    {
+      id: "node",
+      title: "Node.js / Express SDK",
+      package: "@arkveil/node",
+      platform: "Node.js (Express, Fastify, and other HTTP frameworks)",
+      frameworks: ["Express", "Fastify", "Node.js HTTP"],
+      whenToUse: "Use in a non-Nest Node.js HTTP server. Provides a `permissionPoint(code)` middleware for Express/Fastify-style apps.",
+      install: "npm install @arkveil/node arkveil",
+      quickStart: `import { Arkveil } from "@arkveil/node";
+
+const arkveil = new Arkveil({
+  serviceUrl: "https://api.arkveil.com",
+  apiKey: process.env.ARKVEIL_API_KEY!,
+  getUserAttributes: (req) => ({ id: req.user?.id, role: req.user?.role }),
+  onDenied: (req, res) => res.status(403).json({ error: "Forbidden" }),
+});
+
+app.post(
+  "/api/admin",
+  arkveil.permissionPoint("content-service.article-delete"),
+  (req, res) => res.json({ message: "Protected content" }),
+);`,
+      docs: "https://www.npmjs.com/package/@arkveil/node"
+    },
+    {
+      id: "core",
+      title: "Core SDK (runtime-agnostic)",
+      package: "arkveil",
+      platform: "Any JavaScript runtime (Node.js, edge, workers, browser)",
+      frameworks: ["any"],
+      whenToUse: "Use when you want to call Arkveil directly (no middleware), or to build your own platform integration. @arkveil/node and @arkveil/nest are built on top of this.",
+      install: "npm install arkveil",
+      quickStart: `import { Arkveil } from "arkveil";
+
+const arkveil = new Arkveil({
+  serviceUrl: "https://api.arkveil.com",
+  apiKey: process.env.ARKVEIL_API_KEY!,
+});
+
+const { granted } = await arkveil.checkPermission({
+  code: "content-service.article-delete",
+  user: { id: "user-123", role: "admin" },
+  context: {},
+});
+
+if (granted) {
+  // allow
+} else {
+  // deny
+}`,
+      docs: "https://www.npmjs.com/package/arkveil"
+    }
+  ],
+  typing: {
+    summary: "The SDK is typed by declaration merging. `arkveil generate typescript` reads this project's permission codes and user/context JSON Schemas and writes one TypeScript file that augments the SDK registries. Until you import it, attributes are Record<string, any> and codes are string, so untyped usage keeps working.",
+    command: "arkveil generate typescript -o src/arkveil.generated.ts",
+    registries: [
+      {
+        interface: "ArkveilUserRegistry",
+        key: "attributes",
+        resolves: "ArkveilUser",
+        source: "arkveil schemas get user --json"
+      },
+      {
+        interface: "ArkveilContextRegistry",
+        key: "attributes",
+        resolves: "ArkveilContext",
+        source: "arkveil schemas get context --json"
+      },
+      {
+        interface: "ArkveilCodeRegistry",
+        key: "codes",
+        resolves: "ArkveilCode",
+        source: "the permission/action codes defined in your project"
+      }
+    ],
+    steps: [
+      "Run `arkveil generate typescript -o src/arkveil.generated.ts` \u2014 it fetches the codes + attribute schemas and writes the typed file for you (use `--include user,context` to skip codes).",
+      'Import the generated file once as a side-effect import (`import "./arkveil.generated"`) so the `declare module "arkveil"` augmentation is in scope.',
+      "Permission codes plus `getUserAttributes`, `getContextAttributes`, and `checkPermission` are now type-checked against this project.",
+      "Re-run the command whenever the project's codes or attribute schemas change to keep the types in sync.",
+      "Manual alternative: `arkveil schemas get user|context --json` returns the raw JSON Schema (under `.jsonSchema`) if you prefer to generate the types yourself."
+    ],
+    example: `// arkveil-attributes.generated.ts \u2014 generated from \`arkveil schemas get\`
+export interface ArkveilUserAttributes {
+  id?: string;
+  role: "admin" | "editor" | "viewer";
+}
+
+export interface ArkveilContextAttributes {
+  ipAddress?: string;
+  region?: "EU" | "US";
+}
+
+declare module "arkveil" {
+  interface ArkveilUserRegistry {
+    attributes: ArkveilUserAttributes;
+  }
+  interface ArkveilContextRegistry {
+    attributes: ArkveilContextAttributes;
+  }
+}`
+  }
+};
+function findTarget(id) {
+  return SDK_CATALOG.targets.find((t) => t.id === id);
+}
+var SDK_TARGET_IDS = SDK_CATALOG.targets.map((t) => t.id);
+function renderTarget(t) {
+  return [
+    `${t.title}  (${t.package})`,
+    `  Platform:   ${t.platform}`,
+    `  Frameworks: ${t.frameworks.join(", ")}`,
+    `  When:       ${t.whenToUse}`,
+    `  Install:    ${t.install}`,
+    "",
+    indent(t.quickStart, 2)
+  ].join("\n");
+}
+function renderTyping(typing) {
+  const registries = typing.registries.map(
+    (r2) => `  \u2022 ${r2.interface} (key "${r2.key}") \u2192 ${r2.resolves}
+      from: ${r2.source}`
+  ).join("\n");
+  const steps = typing.steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n");
+  return [
+    "TYPED CODES, USER & CONTEXT ATTRIBUTES",
+    `  ${typing.summary}`,
+    "",
+    `  Generate it:  ${typing.command}`,
+    "",
+    "  Registries to augment:",
+    registries,
+    "",
+    "  Steps:",
+    steps,
+    "",
+    "  Example generated file:",
+    indent(typing.example, 4)
+  ].join("\n");
+}
+function renderCatalog(target) {
+  const c = SDK_CATALOG;
+  const header = [
+    "Arkveil SDK \u2014 install & usage",
+    "",
+    `Language:     ${c.language}`,
+    `Registry:     ${c.registry}`,
+    `Requirements: Node ${c.requirements.node}, TypeScript ${c.requirements.typescript}`,
+    "",
+    c.note
+  ].join("\n");
+  if (target) {
+    return [header, "", renderTarget(target)].join("\n");
+  }
+  const targets = c.targets.map(renderTarget).join("\n\n");
+  return [
+    header,
+    "",
+    "TARGETS",
+    "",
+    targets,
+    "",
+    renderTyping(c.typing),
+    "",
+    "See also: `arkveil sdk install <core|node|nest>`, `arkveil schemas get <user|context>`."
+  ].join("\n");
+}
+function indent(text, spaces) {
+  const pad = " ".repeat(spaces);
+  return text.split("\n").map((line) => line.length > 0 ? pad + line : line).join("\n");
+}
+
+// src/commands/sdk/info.ts
+function sdkInfo(ctx, target) {
+  if (target !== void 0 && !findTarget(target)) {
+    throw new UsageError(
+      `Unknown SDK target "${target}".`,
+      `Choose one of: ${SDK_TARGET_IDS.join(", ")}.`
+    );
+  }
+  const selected = target ? findTarget(target) : void 0;
+  const jsonValue = selected ? { ...SDK_CATALOG, targets: [selected] } : SDK_CATALOG;
+  ctx.out.data(jsonValue, () => renderCatalog(selected));
+  return Promise.resolve();
+}
+
+// src/commands/sdk/install.ts
+function sdkInstall(ctx, target) {
+  const t = findTarget(target);
+  if (!t) {
+    throw new UsageError(
+      `Unknown SDK target "${target}".`,
+      `Choose one of: ${SDK_TARGET_IDS.join(", ")}.`
+    );
+  }
+  ctx.out.data(
+    { id: t.id, package: t.package, install: t.install, registry: SDK_CATALOG.registry },
+    () => t.install
+  );
+  return Promise.resolve();
+}
+
+// src/commands/sdk/index.ts
+var TARGET_CHOICES = SDK_TARGET_IDS;
+function registerSdk(program2) {
+  const sdk = program2.command("sdk").description("How to install and use the Arkveil SDK (for humans and AI agents)");
+  sdk.command("info").description("Print SDK install + usage info (all targets, or one)").addArgument(
+    new Argument("[target]", "limit to one SDK target").choices(TARGET_CHOICES)
+  ).addHelpText(
+    "after",
+    `
+Targets:
+  nest   NestJS app          (@arkveil/nest)
+  node   Node.js / Express   (@arkveil/node)
+  core   runtime-agnostic    (arkveil)
+
+For AI agents: \`arkveil sdk info --json\` emits the full machine-readable
+catalog \u2014 packages, install commands, usage snippets, and the recipe to type
+the SDK from your project's attribute schemas (\`arkveil schemas get user|context\`).
+
+Examples:
+  $ arkveil sdk info                 # everything
+  $ arkveil sdk info nest            # just the NestJS package
+  $ arkveil sdk info --json | jq .   # structured output for tooling/agents
+`
+  ).action(async (target, _options, command) => {
+    await run(command, (ctx) => sdkInfo(ctx, target));
+  });
+  sdk.command("install").description("Print the npm install command for an SDK target").addArgument(
+    new Argument("<target>", "SDK target to install").choices(TARGET_CHOICES)
+  ).addHelpText(
+    "after",
+    '\nExample:\n  $ arkveil sdk install nest\n  $ eval "$(arkveil sdk install node)"\n'
+  ).action(async (target, _options, command) => {
+    await run(command, (ctx) => sdkInstall(ctx, target));
+  });
+}
+
+// src/commands/generate/typescript.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+import { resolve } from "path";
+
+// src/lib/json-schema-to-ts.ts
+var IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function tsLiteral(value) {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value === null) return "null";
+  return JSON.stringify(value);
+}
+function dedupe(values) {
+  return [...new Set(values)];
+}
+function commentText(text) {
+  return text.replace(/\*\//g, "*\\/").replace(/\s+/g, " ").trim();
+}
+function indentOf(spaces) {
+  return " ".repeat(spaces);
+}
+function resolveRef(ref, ctx) {
+  const local = ref.match(/^#\/(\$defs|definitions)\/(.+)$/);
+  if (!local) return void 0;
+  const bag = local[1] === "$defs" ? ctx.root.$defs : ctx.root.definitions;
+  const key = decodeURIComponent(local[2]);
+  return bag?.[key];
+}
+function needsParensForArray(t) {
+  return t.includes("|") || t.includes("&");
+}
+function arrayType2(schema, indent2, ctx) {
+  if (Array.isArray(schema.items)) {
+    const tuple = schema.items.map((s) => schemaToType(s, indent2, ctx)).join(", ");
+    return `[${tuple}]`;
+  }
+  const item = schema.items ? schemaToType(schema.items, indent2, ctx) : "unknown";
+  return needsParensForArray(item) ? `(${item})[]` : `${item}[]`;
+}
+function objectType2(schema, indent2, ctx) {
+  const props = schema.properties ?? {};
+  const keys = Object.keys(props);
+  const required = new Set(schema.required ?? []);
+  const inner = indent2 + 2;
+  const lines = [];
+  for (const key of keys) {
+    const propSchema = props[key];
+    const optional = required.has(key) ? "" : "?";
+    const safeKey = IDENTIFIER.test(key) ? key : JSON.stringify(key);
+    if (typeof propSchema.description === "string" && propSchema.description.trim()) {
+      lines.push(`${indentOf(inner)}/** ${commentText(propSchema.description)} */`);
+    }
+    lines.push(
+      `${indentOf(inner)}${safeKey}${optional}: ${schemaToType(propSchema, inner, ctx)};`
+    );
+  }
+  const ap = schema.additionalProperties;
+  if (ap && ap !== true) {
+    lines.push(`${indentOf(inner)}[key: string]: ${schemaToType(ap, inner, ctx)};`);
+  } else if (ap === true) {
+    lines.push(`${indentOf(inner)}[key: string]: unknown;`);
+  }
+  if (lines.length === 0) {
+    return ap === false ? "Record<string, never>" : "Record<string, unknown>";
+  }
+  return `{
+${lines.join("\n")}
+${indentOf(indent2)}}`;
+}
+function unionOf(schemas, indent2, ctx) {
+  const parts = dedupe(schemas.map((s) => schemaToType(s, indent2, ctx)));
+  return parts.length > 0 ? parts.join(" | ") : "unknown";
+}
+function schemaToType(schema, indent2 = 0, ctx = {
+  root: typeof schema === "object" && schema ? schema : {},
+  seen: /* @__PURE__ */ new Set()
+}) {
+  if (schema === void 0 || schema === true) return "unknown";
+  if (schema === false) return "never";
+  if (typeof schema.$ref === "string") {
+    if (ctx.seen.has(schema.$ref)) return "unknown";
+    const resolved = resolveRef(schema.$ref, ctx);
+    if (!resolved) return "unknown";
+    ctx.seen.add(schema.$ref);
+    const t = schemaToType(resolved, indent2, ctx);
+    ctx.seen.delete(schema.$ref);
+    return t;
+  }
+  if (schema.const !== void 0) return tsLiteral(schema.const);
+  if (Array.isArray(schema.enum)) {
+    const union = dedupe(schema.enum.map(tsLiteral));
+    return union.length > 0 ? union.join(" | ") : "never";
+  }
+  if (Array.isArray(schema.anyOf)) return unionOf(schema.anyOf, indent2, ctx);
+  if (Array.isArray(schema.oneOf)) return unionOf(schema.oneOf, indent2, ctx);
+  if (Array.isArray(schema.allOf)) {
+    const parts = dedupe(schema.allOf.map((s) => schemaToType(s, indent2, ctx)));
+    return parts.length > 0 ? parts.join(" & ") : "unknown";
+  }
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  const withNullable = (t) => schema.nullable && !t.split("|").map((s) => s.trim()).includes("null") ? `${t} | null` : t;
+  if (types.length === 0) return withNullable("unknown");
+  if (types.length > 1) {
+    const parts = dedupe(
+      types.map(
+        (t) => t === "null" ? "null" : schemaToType({ ...schema, type: t }, indent2, ctx)
+      )
+    );
+    return parts.join(" | ");
+  }
+  switch (types[0]) {
+    case "string":
+      return withNullable("string");
+    case "integer":
+    case "number":
+      return withNullable("number");
+    case "boolean":
+      return withNullable("boolean");
+    case "null":
+      return "null";
+    case "array":
+      return withNullable(arrayType2(schema, indent2, ctx));
+    case "object":
+      return withNullable(objectType2(schema, indent2, ctx));
+    default:
+      return withNullable("unknown");
+  }
+}
+function schemaToNamedType(name, schema, description) {
+  const ctx = { root: schema, seen: /* @__PURE__ */ new Set() };
+  const body = schemaToType(schema, 0, ctx);
+  const doc = description && description.trim() ? `/** ${commentText(description)} */
+` : "";
+  if (body.startsWith("{")) {
+    return `${doc}export interface ${name} ${body}`;
+  }
+  return `${doc}export type ${name} = ${body};`;
+}
+
+// src/commands/generate/assemble.ts
+var TYPE_NAMES = {
+  codes: "ArkveilCodes",
+  user: "ArkveilUserAttributes",
+  context: "ArkveilContextAttributes"
+};
+var HEADER = `// AUTO-GENERATED by \`arkveil generate typescript\`. Do not edit by hand.
+//
+// This file types the Arkveil SDK for TypeScript by declaration-merging into
+// the \`arkveil\` package. Import it once (a side-effect import is enough) and
+// permission codes plus \`user\` / \`context\` attributes become typed across
+// \`checkPermission\`, the Node \`permissionPoint\` middleware, and the NestJS
+// \`@PermissionPoint\` decorator. Regenerate whenever codes or schemas change.`;
+function renderCodes(codes) {
+  if (codes.length === 0) {
+    return `/** No permission codes were found in this project (falls back to \`string\`). */
+export type ${TYPE_NAMES.codes} = string;`;
+  }
+  const union = codes.map((c) => `  | ${JSON.stringify(c)}`).join("\n");
+  return `/** Union of every permission code defined in this Arkveil project. */
+export type ${TYPE_NAMES.codes} =
+${union};`;
+}
+function assembleTypeScript(input) {
+  const blocks = [HEADER];
+  const augment = [];
+  if (input.codes !== void 0) {
+    blocks.push(renderCodes(input.codes));
+    augment.push(`  interface ArkveilCodeRegistry {
+    codes: ${TYPE_NAMES.codes};
+  }`);
+  }
+  if (input.userSchema !== void 0) {
+    blocks.push(
+      schemaToNamedType(
+        TYPE_NAMES.user,
+        input.userSchema,
+        "Shape of `user` attributes (from `arkveil schemas get user`)."
+      )
+    );
+    augment.push(
+      `  interface ArkveilUserRegistry {
+    attributes: ${TYPE_NAMES.user};
+  }`
+    );
+  }
+  if (input.contextSchema !== void 0) {
+    blocks.push(
+      schemaToNamedType(
+        TYPE_NAMES.context,
+        input.contextSchema,
+        "Shape of `context` attributes (from `arkveil schemas get context`)."
+      )
+    );
+    augment.push(
+      `  interface ArkveilContextRegistry {
+    attributes: ${TYPE_NAMES.context};
+  }`
+    );
+  }
+  blocks.push(
+    `// Register the generated types globally so the default \`Arkveil\` generics
+// pick them up automatically \u2014 no need to pass them everywhere.
+declare module "arkveil" {
+${augment.join("\n")}
+}`
+  );
+  return `${blocks.join("\n\n")}
+`;
+}
+
+// src/commands/generate/typescript.ts
+var ALL_INCLUDES = ["codes", "user", "context"];
+function parseInclude(value) {
+  if (value === void 0) return ALL_INCLUDES;
+  const items = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (items.length === 0) {
+    throw new UsageError(
+      "--include must list at least one of: codes, user, context.",
+      "Example: --include user,context"
+    );
+  }
+  const invalid = items.filter((i) => !ALL_INCLUDES.includes(i));
+  if (invalid.length > 0) {
+    throw new UsageError(
+      `Unknown --include value(s): ${invalid.join(", ")}.`,
+      "Allowed values are: codes, user, context."
+    );
+  }
+  return ALL_INCLUDES.filter((i) => items.includes(i));
+}
+function collectActionCodes(node, into) {
+  if (node.resourceType === "ACTION" && node.resource && "code" in node.resource) {
+    const code = node.resource.code;
+    if (typeof code === "string" && code.length > 0) into.add(code);
+  }
+  for (const child of node.children ?? []) {
+    collectActionCodes(child, into);
+  }
+}
+async function fetchSchema(ctx, type) {
+  const client = await ctx.getClient({ requireAuth: true });
+  const res = await unwrap(
+    client.GET("/api/v1/attribute-schemas/{type}", { params: { path: { type } } }),
+    "GET"
+  );
+  return res.jsonSchema ?? {};
+}
+async function fetchActionCodes(ctx) {
+  const client = await ctx.getClient({ requireAuth: true });
+  const tree = await unwrap(
+    client.GET("/api/v1/navigation/trees/actions"),
+    "GET"
+  );
+  const codes = /* @__PURE__ */ new Set();
+  if (tree?.root) collectActionCodes(tree.root, codes);
+  return [...codes].sort();
+}
+async function generateTypeScript(ctx, options) {
+  const include = parseInclude(options.include);
+  const spinner = ctx.out.spinner("Generating TypeScript\u2026");
+  const input = {};
+  let codes = [];
+  try {
+    if (include.includes("codes")) {
+      codes = await fetchActionCodes(ctx);
+      input.codes = codes;
+    }
+    if (include.includes("user")) {
+      input.userSchema = await fetchSchema(ctx, "user");
+    }
+    if (include.includes("context")) {
+      input.contextSchema = await fetchSchema(ctx, "context");
+    }
+    spinner.stop();
+  } catch (err) {
+    spinner.fail("Could not generate TypeScript.");
+    throw err;
+  }
+  const code = assembleTypeScript(input);
+  if (include.includes("codes") && codes.length === 0) {
+    ctx.out.warn(
+      "No permission codes found; ArkveilCodes falls back to `string`. Define actions first."
+    );
+  }
+  if (options.output) {
+    const target = resolve(process.cwd(), options.output);
+    writeFileSync2(target, code, "utf8");
+    ctx.out.success(`Wrote ${include.join(", ")} TypeScript to ${target}`);
+    ctx.out.data({ output: target, include, codeCount: codes.length }, () => void 0);
+    return;
+  }
+  ctx.out.data(
+    { language: "typescript", include, codeCount: codes.length, code },
+    () => code
+  );
+}
+
+// src/commands/generate/index.ts
+function registerGenerate(program2) {
+  const generate = program2.command("generate").alias("gen").description("Generate typed SDK code from this project (TypeScript)");
+  generate.command("typescript").alias("ts").description("Generate a TypeScript file that types the Arkveil SDK").option(
+    "--include <items>",
+    "comma-separated subset of codes,user,context",
+    "codes,user,context"
+  ).option("-o, --output <file>", "write to a file instead of stdout").addHelpText(
+    "after",
+    `
+Generates TypeScript that types the Arkveil SDK by declaration-merging into the
+\`arkveil\` package: a permission-code union (ArkveilCodes) and \`user\` /
+\`context\` attribute types (ArkveilUserAttributes / ArkveilContextAttributes),
+sourced from this project's actions and attribute schemas. Import the file once
+(a side-effect import is enough) and the SDK becomes typed.
+
+This emits TypeScript only \u2014 there is no codegen for other languages yet.
+
+Examples:
+  $ arkveil generate typescript -o src/arkveil.generated.ts
+  $ arkveil gen ts --include user,context > src/arkveil.generated.ts
+  $ arkveil generate typescript --json        # { language, include, code, \u2026 }
+`
+  ).action(async (options, command) => {
+    await run(command, (ctx) => generateTypeScript(ctx, options));
+  });
+}
+
 // src/commands/folders/create.ts
 async function createFolder(ctx, options) {
   const body = {
@@ -13669,12 +14280,13 @@ async function deletePolicy(ctx, targetNodeId, policyId, options) {
 // src/commands/policies/index.ts
 var POLICY_TYPES = ["PERMISSION", "READ", "WRITE", "INVARIANT", "PROJECTION"];
 var POLICY_STATUSES = ["ENABLED", "DISABLED", "DRAFT", "DELETED"];
+var DSL_HELP = "\n--condition and --filter use the Arkveil formula DSL.\nRun `arkveil formula syntax` for the full reference, or `arkveil formula parse` to validate a formula.\n";
 function registerPolicies(program2) {
   const policies = program2.command("policies").description("Manage policies attached to a target");
-  policies.command("create <targetNodeId>").description("Create a policy under a target").addOption(new Option("--type <type>", "policy type").choices(POLICY_TYPES).makeOptionMandatory()).addOption(new Option("--status <status>", "policy status").choices(POLICY_STATUSES).makeOptionMandatory()).requiredOption("--title <title>", "policy title").option("--description <text>", "description").option("--condition <dsl>", "condition DSL").option("--filter <dsl>", "filter DSL (data policies)").option("--projection <json>", "projection: inline JSON, @file, or -").action(async (targetNodeId, options, command) => {
+  policies.command("create <targetNodeId>").description("Create a policy under a target").addOption(new Option("--type <type>", "policy type").choices(POLICY_TYPES).makeOptionMandatory()).addOption(new Option("--status <status>", "policy status").choices(POLICY_STATUSES).makeOptionMandatory()).requiredOption("--title <title>", "policy title").option("--description <text>", "description").option("--condition <dsl>", "condition DSL").option("--filter <dsl>", "filter DSL (data policies)").option("--projection <json>", "projection: inline JSON, @file, or -").addHelpText("after", DSL_HELP).action(async (targetNodeId, options, command) => {
     await run(command, (ctx) => createPolicy(ctx, targetNodeId, options));
   });
-  policies.command("update <targetNodeId> <policyId>").description("Update a policy").addOption(new Option("--status <status>", "policy status").choices(POLICY_STATUSES).makeOptionMandatory()).requiredOption("--title <title>", "policy title").option("--description <text>", "description").option("--condition <dsl>", "condition DSL").option("--filter <dsl>", "filter DSL (data policies)").option("--projection <json>", "projection: inline JSON, @file, or -").action(
+  policies.command("update <targetNodeId> <policyId>").description("Update a policy").addOption(new Option("--status <status>", "policy status").choices(POLICY_STATUSES).makeOptionMandatory()).requiredOption("--title <title>", "policy title").option("--description <text>", "description").option("--condition <dsl>", "condition DSL").option("--filter <dsl>", "filter DSL (data policies)").option("--projection <json>", "projection: inline JSON, @file, or -").addHelpText("after", DSL_HELP).action(
     async (targetNodeId, policyId, options, command) => {
       await run(command, (ctx) => updatePolicy(ctx, targetNodeId, policyId, options));
     }
@@ -14009,6 +14621,105 @@ async function parseFormula(ctx, options) {
   ctx.out.data(ast, () => JSON.stringify(ast, null, 2));
 }
 
+// src/commands/formula/syntax.ts
+var FORMULA_SYNTAX_REFERENCE = `Arkveil Formula DSL \u2014 syntax reference
+
+A formula is a single boolean expression evaluated against the attributes of a
+request; it returns true or false. Formulas are used for policy conditions and
+filters, target conditions, and test selectors.
+
+ATTRIBUTE REFERENCES
+  Read request attributes through one of four roots. The dot is part of the
+  keyword \u2014 write "user.role", not "user . role":
+
+    user.<path>      e.g. user.role, user.profile.age
+    context.<path>   e.g. context.country, context.time.hour   (note: "context.", not "ctx.")
+    action.<path>    e.g. action.name, action.tags
+    request.<path>   e.g. request.invoice.amount
+
+  Paths may be nested with dots: request.invoice.line.total
+
+LITERALS
+  String    "double quoted"     escape an inner quote with \\"   e.g. "O\\"Brien"
+  Integer   42                   whole numbers only \u2014 no decimals, no negatives
+  Boolean   true   false
+  Array     ["a","b"]  [1,2,3]  [true,false]
+              \u2022 never empty
+              \u2022 all elements must be the same type
+              \u2022 elements are literals only (no attribute references inside an array)
+
+COMPARISON
+  =      equal        user.role = "admin"
+  !=     not equal    user.status != "blocked"
+
+  Equality is a single "=" (NOT "=="). "==" is not valid.
+
+STRING PREDICATES        left <op> right
+  contains                request.path contains "/admin"
+  containsIgnoreCase      user.email containsIgnoreCase "@Arkveil.com"
+  startsWith              action.name startsWith "delete"
+  startsWithIgnoreCase    action.name startsWithIgnoreCase "Delete"
+  matches                 user.name matches "^A.*"          (regular expression)
+
+PRESENCE / SET / COLLECTION CHECKS
+  is null              user.manager is null
+  is not null          user.manager is not null
+  in <array>           user.role in ["admin","editor"]
+  not in <array>       context.region not in ["EU","UK"]
+  is empty             action.tags is empty
+  is not empty         action.tags is not empty
+  is uniform           request.amounts is uniform     (all elements are equal)
+  is diverse           request.amounts is diverse     (elements are not all equal)
+
+BOOLEAN LOGIC          precedence, lowest to highest:  or  <  and  <  not
+  and     user.active = true and context.country = "US"
+  or      user.isOwner = true or user.role = "admin"
+  not     not (user.suspended = true)
+
+  Keywords are lowercase. Use parentheses to group: (a or b) and c
+
+ITERATIVE PREDICATES OVER COLLECTIONS
+  Test the elements of an array. <condition> is a full boolean expression in
+  which "it" refers to the current element:
+
+    any    <collection> [as <alias>] where <condition>    at least one element matches
+    all    <collection> [as <alias>] where <condition>    every element matches
+    every  <collection> [as <alias>] where <condition>    every element matches
+    none   <collection> [as <alias>] where <condition>    no element matches
+    exists <collection> [as <alias>] where <condition>    at least one element matches
+
+  \u2022 <collection> must be an array attribute (user./context./action./request.)
+    or an array literal. It cannot be "it", a scalar literal, or a parenthesized
+    expression.
+  \u2022 Because <condition> is a full expression, "and"/"or" bind INSIDE the where:
+        any user.tags where it = "a" or it = "b"
+    To combine a whole iterative predicate with an outer expression, wrap it in
+    parentheses:
+        (any user.tags where it = "a") or user.active = true
+  \u2022 Each <collection> must be one of those roots or an array literal \u2014 you cannot
+    iterate an alias element (e.g. "g.members" is not a valid collection).
+  \u2022 For nested iteration, name the outer collection with "as" and reference its
+    current element as <alias>.it ("it" alone is always the innermost element):
+        any user.groups as g where any context.allowedGroups where it = g.it
+
+EXAMPLES
+  user.role = "admin"
+  user.role = "admin" and context.country = "US"
+  not (user.suspended = true) and user.role in ["admin","editor"]
+  request.path startsWith "/admin/" and user.clearance != "none"
+  action.tags is not empty and none action.tags where it = "blocked"
+  any user.permissions where it startsWith "billing:"
+  all request.items as line where line.it != ""
+  (any user.tags where it = "vip") or user.isOwner = true
+`;
+function formulaSyntax(ctx) {
+  ctx.out.data(
+    { dsl: "arkveil-formula", reference: FORMULA_SYNTAX_REFERENCE },
+    () => FORMULA_SYNTAX_REFERENCE
+  );
+  return Promise.resolve();
+}
+
 // src/commands/formula/index.ts
 var CONTEXTS = [
   "ACTION_PERMISSION",
@@ -14020,12 +14731,15 @@ var CONTEXTS = [
 ];
 function registerFormula(program2) {
   const formula = program2.command("formula").description("Work with the formula DSL");
+  formula.command("syntax").description("Print the formula DSL syntax reference").addHelpText(
+    "after",
+    "\nThe full DSL reference (operators, predicates, collections, examples) is\nprinted to stdout. Pipe it anywhere, e.g. `arkveil formula syntax | less`.\n"
+  ).action(async (_options, command) => {
+    await run(command, formulaSyntax);
+  });
   formula.command("parse").description("Parse a formula DSL string into its AST").requiredOption("--dsl <dsl>", "the formula DSL to parse").addOption(new Option("--context <context>", "evaluation context").choices(CONTEXTS).makeOptionMandatory()).option("--request-schema <json>", "request schema: inline JSON, @file, or -").addHelpText(
     "after",
-    `
-Example:
-  $ arkveil formula parse --context ACTION_PERMISSION --dsl 'user.role == "admin"'
-`
+    "\nExample:\n  $ arkveil formula parse --context ACTION_PERMISSION --dsl 'user.role = \"admin\"'\n\nSee `arkveil formula syntax` for the full DSL reference.\n"
   ).action(
     async (options, command) => {
       await run(command, (ctx) => parseFormula(ctx, options));
@@ -14240,12 +14954,255 @@ function registerAdmin(program2) {
   });
 }
 
+// src/commands/update/update.ts
+import { execFile as execFile6 } from "child_process";
+import { fileURLToPath as fileURLToPath3 } from "url";
+
+// src/commands/update/npm.ts
+import { existsSync, readFileSync as readFileSync4 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname, join as join2, parse } from "path";
+function readPackageMeta() {
+  let dir = dirname(fileURLToPath2(import.meta.url));
+  const { root } = parse(dir);
+  while (true) {
+    const candidate = join2(dir, "package.json");
+    if (existsSync(candidate)) {
+      const pkg = JSON.parse(readFileSync4(candidate, "utf8"));
+      return { name: pkg.name ?? "@arkveil/cli", version: pkg.version ?? "0.0.0" };
+    }
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  return { name: "@arkveil/cli", version: "0.0.0" };
+}
+function parseSemver(version) {
+  const cleaned = version.trim().replace(/^v/, "");
+  const [main3 = "", pre = null] = cleaned.split("-", 2);
+  const core = main3.split(".").map((p) => Number.parseInt(p, 10) || 0);
+  while (core.length < 3) core.push(0);
+  return { core: core.slice(0, 3), pre: pre ?? null };
+}
+function compareSemver(a3, b3) {
+  const pa = parseSemver(a3);
+  const pb = parseSemver(b3);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa.core[i] ?? 0) - (pb.core[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1;
+  if (pb.pre === null) return -1;
+  return pa.pre < pb.pre ? -1 : 1;
+}
+var PACKAGE_MANAGERS = ["pnpm", "yarn", "bun", "npm"];
+function detectPackageManager(modulePath, env2 = process.env) {
+  const path2 = modulePath.toLowerCase();
+  if (path2.includes("pnpm")) return "pnpm";
+  if (path2.includes(`${"/"}.bun${"/"}`) || path2.includes("/bun/")) return "bun";
+  if (path2.includes(".yarn") || path2.includes("/yarn/")) return "yarn";
+  const agent = (env2.npm_config_user_agent ?? "").toLowerCase();
+  const fromAgent = PACKAGE_MANAGERS.find((pm) => agent.startsWith(pm));
+  if (fromAgent) return fromAgent;
+  return "npm";
+}
+function installCommand(pm, spec) {
+  switch (pm) {
+    case "pnpm":
+      return { cmd: "pnpm", args: ["add", "-g", spec] };
+    case "yarn":
+      return { cmd: "yarn", args: ["global", "add", spec] };
+    case "bun":
+      return { cmd: "bun", args: ["add", "-g", spec] };
+    case "npm":
+    default:
+      return { cmd: "npm", args: ["install", "-g", spec] };
+  }
+}
+async function fetchLatestVersion(opts) {
+  const tag = opts.tag ?? "latest";
+  const registry = (opts.registry ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+  const encoded = opts.name.replace("/", "%2f");
+  const url = `${registry}/${encoded}/${tag}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 1e4);
+  try {
+    const res = await fetch(url, {
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      throw new NetworkError(
+        `npm registry returned ${res.status} for ${opts.name}@${tag}.`,
+        "Check your network connection and that the package/tag exists."
+      );
+    }
+    const body = await res.json();
+    if (!body.version) {
+      throw new NetworkError(
+        `npm registry response for ${opts.name}@${tag} had no version.`
+      );
+    }
+    return body.version;
+  } catch (err) {
+    if (err instanceof NetworkError) throw err;
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new NetworkError(
+        `Timed out contacting the npm registry for ${opts.name}@${tag}.`,
+        "Retry, or increase the timeout with --timeout <ms>.",
+        err
+      );
+    }
+    throw new NetworkError(
+      `Could not reach the npm registry: ${err instanceof Error ? err.message : String(err)}`,
+      "Check your network connection.",
+      err
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// src/commands/update/update.ts
+var VALID_PMS = ["npm", "pnpm", "yarn", "bun"];
+async function selfUpdate(ctx, options) {
+  const { out, config } = ctx;
+  const meta = readPackageMeta();
+  const tag = options.tag ?? "latest";
+  if (options.use && !VALID_PMS.includes(options.use)) {
+    throw new CliError(`Unknown package manager "${options.use}".`, {
+      exitCode: ExitCode.Usage,
+      hint: `Choose one of: ${VALID_PMS.join(", ")}.`
+    });
+  }
+  const spinner = out.spinner(`Checking npm for ${meta.name}@${tag}\u2026`);
+  let latest;
+  try {
+    latest = await fetchLatestVersion({
+      name: meta.name,
+      tag,
+      timeoutMs: config.timeoutMs
+    });
+    spinner.stop();
+  } catch (err) {
+    spinner.fail("Could not check for updates.");
+    throw err;
+  }
+  const cmp = compareSemver(meta.version, latest);
+  const upToDate = cmp >= 0;
+  const willUpdate = !upToDate || Boolean(options.force);
+  const pm = options.use ?? detectPackageManager(fileURLToPath3(import.meta.url));
+  const spec = `${meta.name}@${tag}`;
+  const { cmd, args } = installCommand(pm, spec);
+  const commandLine = `${cmd} ${args.join(" ")}`;
+  if (options.check || options.dryRun || !willUpdate) {
+    out.data(
+      {
+        name: meta.name,
+        current: meta.version,
+        latest,
+        tag,
+        updateAvailable: !upToDate,
+        upToDate,
+        packageManager: pm,
+        command: commandLine,
+        action: options.dryRun ? "dry-run" : options.check ? "check" : "none"
+      },
+      (o2) => {
+        if (upToDate) {
+          return `${o2.c.green("\u2714")} ${meta.name} is up to date (${meta.version}).`;
+        }
+        const lines = [
+          `${o2.c.yellow("!")} Update available: ${o2.c.dim(meta.version)} \u2192 ${o2.c.green(latest)}`
+        ];
+        if (options.dryRun) {
+          lines.push(`  Would run: ${o2.c.cyan(commandLine)}`);
+        } else {
+          lines.push(`  Run ${o2.c.cyan("arkveil update")} to upgrade (uses: ${o2.c.cyan(commandLine)}).`);
+        }
+        return lines.join("\n");
+      }
+    );
+    return;
+  }
+  const label = upToDate ? `Reinstalling ${spec}\u2026` : `Updating ${meta.name} ${meta.version} \u2192 ${latest}\u2026`;
+  out.verbose(`Running: ${commandLine}`);
+  const install = out.spinner(label);
+  try {
+    await runInstall(cmd, args);
+    install.succeed(`Updated to ${latest}. Run \`arkveil --version\` to confirm.`);
+  } catch (err) {
+    install.fail("Update failed.");
+    throw toInstallError(err, pm, commandLine);
+  }
+  out.data(
+    {
+      name: meta.name,
+      previous: meta.version,
+      latest,
+      tag,
+      packageManager: pm,
+      command: commandLine,
+      action: "updated"
+    },
+    () => {
+    }
+  );
+}
+function runInstall(cmd, args) {
+  return new Promise((resolve2, reject) => {
+    execFile6(cmd, args, { timeout: 12e4 }, (err) => {
+      if (err) reject(err);
+      else resolve2();
+    });
+  });
+}
+function toInstallError(err, pm, commandLine) {
+  const e2 = err;
+  if (e2?.code === "ENOENT") {
+    return new CliError(`${pm} was not found on your PATH.`, {
+      exitCode: ExitCode.Generic,
+      hint: `Install ${pm}, or pass --use <npm|pnpm|yarn|bun> to pick another package manager.`,
+      cause: err
+    });
+  }
+  const detail = (e2?.stderr ?? e2?.message ?? String(err)).trim().split("\n").slice(-3).join(" ");
+  return new CliError(`Upgrade command failed: ${detail || commandLine}`, {
+    exitCode: ExitCode.Generic,
+    hint: `Try running it yourself: ${commandLine}. A global install may require elevated permissions (sudo).`,
+    cause: err
+  });
+}
+
+// src/commands/update/index.ts
+function registerUpdate(program2) {
+  program2.command("update").aliases(["upgrade", "self-update"]).description("Update the Arkveil CLI to the latest published version").option("--check", "only report whether an update is available; don't install").option("--dry-run", "print the install command that would run, without executing it").option("--tag <tag>", "npm dist-tag to install (default latest)", "latest").option("--use <pm>", "package manager to use: npm, pnpm, yarn, or bun").option("--force", "reinstall even if already on the target version").addHelpText(
+    "after",
+    `
+Checks the npm registry for a newer release of the CLI and upgrades this install
+in place using the package manager that installed it (auto-detected; override
+with --use). Use --check in scripts/CI to detect a pending update via the exit
+output without changing anything.
+
+Examples:
+  $ arkveil update                 # upgrade to the latest release
+  $ arkveil update --check         # is a newer version available?
+  $ arkveil update --dry-run       # show the command without running it
+  $ arkveil update --tag next      # install the "next" dist-tag
+  $ arkveil update --use pnpm      # force pnpm for the global install
+  $ arkveil update --json          # machine-readable result
+`
+  ).action(async (options, command) => {
+    await run(command, (ctx) => selfUpdate(ctx, options));
+  });
+}
+
 // src/index.ts
 function readVersion() {
   try {
-    const here = dirname(fileURLToPath2(import.meta.url));
+    const here = dirname2(fileURLToPath4(import.meta.url));
     const pkg = JSON.parse(
-      readFileSync4(join2(here, "..", "package.json"), "utf8")
+      readFileSync5(join3(here, "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -14273,10 +15230,13 @@ function buildProgram() {
   registerTests(program2);
   registerSettings(program2);
   registerSchemas(program2);
+  registerSdk(program2);
+  registerGenerate(program2);
   registerFormula(program2);
   registerEval(program2);
   registerAbac(program2);
   registerAdmin(program2);
+  registerUpdate(program2);
   program2.addHelpText(
     "after",
     `
@@ -14285,6 +15245,9 @@ Examples:
   $ arkveil health                           Check API connectivity
   $ arkveil tags list --json                 List tags as JSON
   $ arkveil trees forest                     Show the full navigation forest
+  $ arkveil sdk info                         How to install & use the SDK
+  $ arkveil update                           Update the CLI to the latest release
+  $ arkveil formula syntax                   Print the formula DSL reference
   $ arkveil eval explain -a orders:read \\
       --user '{"role":"admin"}' --context '{}'   Explain an access decision