@aaac/contracts 0.1.13 → 0.1.14

package/dist/{chunk-MWZFJ2VL.js → chunk-JWJLY3HJ.js}

@@ -64,6 +64,14 @@ var GovernanceSchema = z.object({
   guardrails: z.boolean().optional(),
   observability: z.boolean().optional()
 }).optional();
+var BindingRefSchema = z.object({
+  /** npm package name implementing the binding (e.g. "@aaac/binding-cursor"). */
+  package: z.string().min(1),
+  /** CLI command name to expose (defaults to the binding id). */
+  command: z.string().optional(),
+  /** Binding-specific configuration; validated by the binding package. */
+  config: z.record(z.string(), z.unknown()).default({})
+});
 var ComponentSchema = z.object({
   schema: z.string().regex(SCHEMA_VERSION_PATTERN, 'schema must match pattern "aaac/x.y"'),
   info: z.object({
@@ -77,6 +85,7 @@ var ComponentSchema = z.object({
     z.enum(["library", "cli", "claude", "openai"])
   ),
   governance: GovernanceSchema,
+  bindings: z.record(z.string(), BindingRefSchema).optional(),
   operations: z.record(z.string(), OperationSchema)
 }).superRefine((component, ctx) => {
   const usesAgentic = Object.values(component.operations).some(
@@ -148,6 +157,7 @@ function normalizeComponent(raw) {
     embedded_dsl_dir: raw.embedded_dsl_dir,
     projections: raw.projections,
     governance: raw.governance,
+    bindings: raw.bindings,
     operations: Object.keys(normalizedOps).length > 0 ? normalizedOps : raw.operations
   };
 }
@@ -568,9 +578,21 @@ function compileComponent(dsl, options = {}) {
       guardrails: dsl.governance.guardrails,
       observability: dsl.governance.observability
     } : void 0,
+    bindings: dsl.bindings ? compileBindings(dsl.bindings) : void 0,
     operations
   };
 }
+function compileBindings(bindings) {
+  const result = {};
+  for (const [id, binding] of Object.entries(bindings)) {
+    result[id] = {
+      package: binding.package,
+      command: binding.command ?? id,
+      config: binding.config ?? {}
+    };
+  }
+  return result;
+}
 async function maybeValidateComponent(ir, options) {
   if (options.validate === false) {
     return;
@@ -593,6 +615,44 @@ async function compileComponentFile(filePath, options = {}) {
   return ir;
 }
 
+// src/generators/bindings-generator.ts
+var bindingsGenerator = {
+  generate(ir, _options) {
+    if (!ir.bindings || Object.keys(ir.bindings).length === 0) {
+      return [];
+    }
+    const entries = Object.entries(ir.bindings).map(([id, binding]) => {
+      return `  ${JSON.stringify(id)}: {
+    package: ${JSON.stringify(binding.package)},
+    command: ${JSON.stringify(binding.command)},
+    config: ${JSON.stringify(binding.config)},
+  },`;
+    });
+    const content = `// Auto-generated by @aaac/contracts. Do not edit.
+
+export interface BindingEntry {
+  /** npm package implementing the binding. */
+  package: string;
+  /** CLI command name exposed for this binding. */
+  command: string;
+  /** Binding-specific configuration (validated by the binding package). */
+  config: Record<string, unknown>;
+}
+
+export const bindings: Record<string, BindingEntry> = {
+${entries.join("\n")}
+};
+`;
+    return [
+      {
+        path: "bindings.generated.ts",
+        content,
+        overwrite: true
+      }
+    ];
+  }
+};
+
 // src/generators/cli-generator.ts
 import { stringify as stringifyYaml } from "yaml";
 function unwrapSchema(ref) {
@@ -878,6 +938,49 @@ function buildPromptCommand() {
 function countAgenticOperations(ir) {
   return Object.values(ir.operations).filter((op) => !op.handler).length;
 }
+function buildBindingCommands(ir) {
+  const commands = {};
+  if (!ir.bindings) {
+    return commands;
+  }
+  for (const [bindingId, binding] of Object.entries(ir.bindings)) {
+    const cmd = binding.command;
+    commands[`${cmd}.sync`] = {
+      summary: `Materialize ${bindingId} binding output files from the embedded DSL`,
+      options: [
+        {
+          name: "dry-run",
+          schema: { type: "boolean" },
+          description: "Report changes without writing files"
+        }
+      ],
+      exits: {
+        "0": { description: "Synced" },
+        "1": { description: "Materialization failed" }
+      },
+      "x-agent": {
+        risk_level: "low",
+        requires_confirmation: false,
+        idempotent: true,
+        binding: bindingId
+      }
+    };
+    commands[`${cmd}.check`] = {
+      summary: `Fail if ${bindingId} binding output drifts from the DSL`,
+      exits: {
+        "0": { description: "In sync" },
+        "2": { description: "Drift detected" }
+      },
+      "x-agent": {
+        risk_level: "low",
+        requires_confirmation: false,
+        idempotent: true,
+        binding: bindingId
+      }
+    };
+  }
+  return commands;
+}
 function buildCliContract(ir) {
   const commands = {};
   for (const [name, op] of Object.entries(ir.operations)) {
@@ -886,6 +989,7 @@ function buildCliContract(ir) {
   if (ir.governance?.guardrails === true) {
     Object.assign(commands, buildGuardCommands());
   }
+  Object.assign(commands, buildBindingCommands(ir));
   if (countAgenticOperations(ir) >= 2) {
     commands.prompt = buildPromptCommand();
   }
@@ -1079,7 +1183,7 @@ var clientGenerator = {
   ctx: AaacInvocationContext,
   memoryRef?: string,
 ): Promise<${names.output}> {
-  return runtime.execute(${JSON.stringify(operationName)}, options, input, ctx, memoryRef);
+  return runtime.execute(${JSON.stringify(operationName)}, options, input, ctx, memoryRef) as Promise<${names.output}>;
 }`;
     });
     if (agenticOpsCount >= 2) {
@@ -1088,7 +1192,7 @@ var clientGenerator = {
   input: { message: string },
   ctx: AaacInvocationContext,
 ): Promise<PromptResult> {
-  return runtime.executePrompt(input.message, options, ctx) as Promise<PromptResult>;
+  return runtime.executePrompt(input.message, options as unknown as Record<string, unknown>, ctx) as Promise<PromptResult>;
 }`);
     }
     const runtimeTypeImports = agenticOpsCount >= 2 ? `import type { PromptResult, PromptExecuteOptions } from "@aaac/runtime";
@@ -1426,7 +1530,8 @@ var ALL_GENERATORS = [
   runtimeGenerator,
   cliGenerator,
   handlerGenerator,
-  embeddedDslGenerator
+  embeddedDslGenerator,
+  bindingsGenerator
 ];
 function generateAll(ir, options) {
   return ALL_GENERATORS.flatMap((gen) => gen.generate(ir, options));
@@ -1463,6 +1568,350 @@ async function writeGeneratedFiles(files, outputDir) {
   return { written, skipped, warnings };
 }
 
+// src/cli/governance.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2 } from "fs";
+import { chmod, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname5, join as join3, resolve as resolve3 } from "path";
+import { parse as parseYaml3 } from "yaml";
+import { z as z2 } from "zod";
+var MANAGED_BLOCK_START = "# >>> aaac-governance:managed (do not edit) >>>";
+var MANAGED_BLOCK_END = "# <<< aaac-governance:managed <<<";
+var GOVERNANCE_LOCK_PATH = ".agent-logs/governance-manifest.lock";
+var DEFAULT_RECORDER = ".cursor/hooks/observ-record.sh";
+var DEFAULT_CURSOR_HOOKS_JSON = ".cursor/hooks.json";
+var DEFAULT_BINARY_DEST = "bin/aaac.js";
+var CURSOR_HOOKS_VERSION = 1;
+var EnvironmentsSchema = z2.object({
+  git: z2.object({ hooks: z2.array(z2.string()).optional() }).optional(),
+  cursor: z2.object({ hooks_json: z2.string().optional() }).optional()
+}).optional();
+var BindingsObservabilitySchema = z2.object({
+  event_mapping: z2.string().optional(),
+  recorder: z2.string().optional()
+}).optional();
+var BindingsSchema = z2.object({
+  observability: BindingsObservabilitySchema,
+  hooks: z2.array(z2.string()).optional()
+}).optional();
+var InitProjectConfigSchema = z2.object({
+  environments: EnvironmentsSchema,
+  bindings: BindingsSchema
+});
+async function loadInitConfig(configPath) {
+  const absPath = resolve3(configPath);
+  const raw = await readFile2(absPath, "utf8");
+  const parsed = parseYaml3(raw);
+  return InitProjectConfigSchema.parse(parsed ?? {});
+}
+var HookCommandSchema = z2.object({
+  command: z2.string(),
+  description: z2.string().optional()
+});
+var HookBindingSchema = z2.object({
+  hooks: z2.record(z2.string(), z2.array(HookCommandSchema)).optional()
+});
+async function loadHookBindings(projectRoot, bindingPaths) {
+  const result = {};
+  if (!bindingPaths?.length) return result;
+  const root = resolve3(projectRoot);
+  for (const bindingPath of bindingPaths) {
+    const absPath = resolve3(root, bindingPath);
+    if (!existsSync2(absPath)) continue;
+    const raw = await readFile2(absPath, "utf8");
+    const parsed = HookBindingSchema.parse(parseYaml3(raw) ?? {});
+    if (!parsed.hooks) continue;
+    for (const [hookName, commands] of Object.entries(parsed.hooks)) {
+      const list = result[hookName] ?? [];
+      for (const { command } of commands) {
+        if (!list.includes(command)) list.push(command);
+      }
+      result[hookName] = list;
+    }
+  }
+  return result;
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function createManagedBlockRegex() {
+  return new RegExp(
+    `${escapeRegex(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegex(MANAGED_BLOCK_END)}\\n?`,
+    "g"
+  );
+}
+function buildManagedBlock(blockContent) {
+  return `${MANAGED_BLOCK_START}
+${blockContent.trimEnd()}
+${MANAGED_BLOCK_END}
+`;
+}
+function injectManagedBlock(existingContent, blockContent) {
+  const managedBlock = buildManagedBlock(blockContent);
+  const re = createManagedBlockRegex();
+  if (re.test(existingContent)) {
+    return existingContent.replace(createManagedBlockRegex(), managedBlock);
+  }
+  const trimmed = existingContent.replace(/\s+$/, "");
+  if (trimmed.length === 0) {
+    return `#!/bin/sh
+${managedBlock}`;
+  }
+  const separator = trimmed.endsWith("\n") ? "" : "\n";
+  return `${trimmed}${separator}${managedBlock}`;
+}
+function removeManagedBlock(existingContent) {
+  if (!existingContent.includes(MANAGED_BLOCK_START)) {
+    return existingContent;
+  }
+  const withoutBlock = existingContent.replace(createManagedBlockRegex(), "");
+  const meaningful = withoutBlock.split("\n").filter((line) => {
+    const t = line.trim();
+    return t.length > 0 && t !== "#!/bin/sh" && t !== "#!/bin/bash";
+  });
+  if (meaningful.length === 0) {
+    return "";
+  }
+  return withoutBlock.replace(/\n{3,}/g, "\n\n").replace(/\s+$/, "\n");
+}
+function parseCursorHooksFile(raw) {
+  if (!raw || !raw.trim()) {
+    return { version: CURSOR_HOOKS_VERSION, hooks: {} };
+  }
+  const parsed = JSON.parse(raw);
+  if (Array.isArray(parsed)) {
+    return flatEntriesToFile(
+      parsed.filter(
+        (entry) => entry !== null && typeof entry === "object" && typeof entry.event === "string" && typeof entry.command === "string"
+      )
+    );
+  }
+  if (parsed && typeof parsed === "object") {
+    const obj = parsed;
+    const version = typeof obj.version === "number" ? obj.version : CURSOR_HOOKS_VERSION;
+    const hooks = {};
+    const rawHooks = obj.hooks;
+    if (rawHooks && typeof rawHooks === "object" && !Array.isArray(rawHooks)) {
+      for (const [event, commands] of Object.entries(rawHooks)) {
+        if (Array.isArray(commands)) {
+          hooks[event] = commands.filter(
+            (c) => c !== null && typeof c === "object" && typeof c.command === "string"
+          );
+        }
+      }
+    }
+    return { version, hooks };
+  }
+  return { version: CURSOR_HOOKS_VERSION, hooks: {} };
+}
+function serializeCursorHooksFile(file) {
+  return JSON.stringify(file, null, 2) + "\n";
+}
+function flatEntriesToFile(entries) {
+  return mergeCursorHooks({ version: CURSOR_HOOKS_VERSION, hooks: {} }, entries);
+}
+function mergeCursorHooks(existing, newEntries) {
+  const hooks = {};
+  for (const [event, commands] of Object.entries(existing.hooks)) {
+    hooks[event] = commands.map((c) => ({ ...c }));
+  }
+  for (const entry of newEntries) {
+    const { event, ...command } = entry;
+    const list = hooks[event] ?? [];
+    const idx = list.findIndex((c) => c.command === command.command);
+    if (idx >= 0) {
+      list[idx] = command;
+    } else {
+      list.push(command);
+    }
+    hooks[event] = list;
+  }
+  return { version: existing.version ?? CURSOR_HOOKS_VERSION, hooks };
+}
+function removeCursorHooks(existing, commands) {
+  const removeSet = new Set(commands);
+  const hooks = {};
+  for (const [event, list] of Object.entries(existing.hooks)) {
+    const filtered = list.filter((c) => !removeSet.has(c.command));
+    if (filtered.length > 0) {
+      hooks[event] = filtered;
+    }
+  }
+  return { version: existing.version ?? CURSOR_HOOKS_VERSION, hooks };
+}
+function buildGitHookBlock(hookName, recorder, gateCommands = []) {
+  const lines = [`${recorder} ${hookName} "$@" || true`];
+  for (const command of gateCommands) {
+    lines.push(`${command} || exit 1`);
+  }
+  return lines.join("\n");
+}
+function buildDefaultCursorHooks(recorder) {
+  return [
+    { event: "beforeSubmitPrompt", command: `${recorder} beforeSubmitPrompt` },
+    { event: "afterShellExecution", command: `${recorder} afterShellExecution` }
+  ];
+}
+async function ensureParentDir(filePath) {
+  await mkdir2(dirname5(filePath), { recursive: true });
+}
+async function readTextFileIfExists(filePath) {
+  if (!existsSync2(filePath)) return void 0;
+  return readFile2(filePath, "utf8");
+}
+async function writeGovernanceLock(projectRoot, entries) {
+  const lockPath = join3(projectRoot, GOVERNANCE_LOCK_PATH);
+  const lock = {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    entries
+  };
+  await ensureParentDir(lockPath);
+  await writeFile2(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  return GOVERNANCE_LOCK_PATH;
+}
+async function readGovernanceLock(projectRoot) {
+  const lockPath = join3(projectRoot, GOVERNANCE_LOCK_PATH);
+  if (!existsSync2(lockPath)) return void 0;
+  const raw = await readFile2(lockPath, "utf8");
+  if (!raw.trim()) return void 0;
+  return JSON.parse(raw);
+}
+async function materializeHooks(options) {
+  const projectRoot = resolve3(options.projectRoot);
+  const result = { materialized: [], lockEntries: [] };
+  const recorder = options.observabilityBinding?.recorder ?? DEFAULT_RECORDER;
+  if (options.environments.git?.hooks?.length) {
+    for (const hookName of options.environments.git.hooks) {
+      const relPath = join3(".git/hooks", hookName);
+      const absPath = join3(projectRoot, relPath);
+      const blockContent = buildGitHookBlock(
+        hookName,
+        recorder,
+        options.hookCommands?.[hookName]
+      );
+      const existing = await readTextFileIfExists(absPath) ?? "";
+      const updated = injectManagedBlock(existing, blockContent);
+      let action = "unchanged";
+      if (!existsSync2(absPath)) {
+        action = "created";
+      } else if (updated !== existing) {
+        action = "updated";
+      }
+      if (action !== "unchanged") {
+        await ensureParentDir(absPath);
+        await writeFile2(absPath, updated, "utf8");
+        await chmod(absPath, 493);
+      }
+      result.materialized.push({ path: relPath, action });
+      result.lockEntries.push({ path: relPath, type: "git-hook" });
+    }
+  }
+  if (options.environments.cursor) {
+    const rawHooksJsonValue = options.environments.cursor.hooks_json;
+    const hooksJsonPath = rawHooksJsonValue ? resolve3(projectRoot, rawHooksJsonValue) : join3(projectRoot, DEFAULT_CURSOR_HOOKS_JSON);
+    const relPath = hooksJsonPath.startsWith(projectRoot + "/") ? hooksJsonPath.slice(projectRoot.length + 1) : DEFAULT_CURSOR_HOOKS_JSON;
+    const newEntries = buildDefaultCursorHooks(recorder);
+    const existingRaw = await readTextFileIfExists(hooksJsonPath);
+    const existing = parseCursorHooksFile(existingRaw);
+    const merged = mergeCursorHooks(existing, newEntries);
+    const serialized = serializeCursorHooksFile(merged);
+    let action = "unchanged";
+    if (!existsSync2(hooksJsonPath)) {
+      action = "created";
+    } else if (serialized !== existingRaw) {
+      action = "updated";
+    }
+    if (action !== "unchanged") {
+      await ensureParentDir(hooksJsonPath);
+      await writeFile2(hooksJsonPath, serialized, "utf8");
+    }
+    result.materialized.push({ path: relPath, action });
+    result.lockEntries.push({ path: relPath, type: "cursor-hook" });
+  }
+  if (result.lockEntries.length > 0) {
+    const lockExisted = existsSync2(join3(projectRoot, GOVERNANCE_LOCK_PATH));
+    await writeGovernanceLock(projectRoot, result.lockEntries);
+    result.materialized.push({
+      path: GOVERNANCE_LOCK_PATH,
+      action: lockExisted ? "updated" : "created"
+    });
+    result.lockEntries.push({ path: GOVERNANCE_LOCK_PATH, type: "generated" });
+  }
+  return result;
+}
+async function unmaterializeHooks(projectRoot, lockEntries) {
+  const root = resolve3(projectRoot);
+  for (const entry of lockEntries) {
+    if (entry.type === "generated") {
+      const absPath = join3(root, entry.path);
+      if (existsSync2(absPath)) {
+        await writeFile2(absPath, "", "utf8");
+      }
+      continue;
+    }
+    if (entry.type === "git-hook") {
+      const absPath = join3(root, entry.path);
+      const existing = await readTextFileIfExists(absPath);
+      if (existing === void 0) continue;
+      const updated = removeManagedBlock(existing);
+      await writeFile2(absPath, updated, "utf8");
+      continue;
+    }
+    if (entry.type === "cursor-hook") {
+      const absPath = join3(root, entry.path);
+      const existingRaw = await readTextFileIfExists(absPath);
+      if (existingRaw === void 0) continue;
+      const existing = parseCursorHooksFile(existingRaw);
+      const commandsToRemove = buildDefaultCursorHooks(DEFAULT_RECORDER).map((h) => h.command);
+      const updated = removeCursorHooks(existing, commandsToRemove);
+      await writeFile2(absPath, serializeCursorHooksFile(updated), "utf8");
+    }
+  }
+  const lockPath = join3(root, GOVERNANCE_LOCK_PATH);
+  if (existsSync2(lockPath)) {
+    await writeFile2(lockPath, "", "utf8");
+  }
+}
+async function copyCLIBinary(srcPath, projectRoot, destRelPath = DEFAULT_BINARY_DEST) {
+  const dstPath = join3(projectRoot, destRelPath);
+  const srcContent = await readFile2(srcPath);
+  const srcHash = createHash("sha256").update(srcContent).digest("hex");
+  if (existsSync2(dstPath)) {
+    const dstContent = await readFile2(dstPath);
+    const dstHash = createHash("sha256").update(dstContent).digest("hex");
+    if (srcHash === dstHash) {
+      return { path: destRelPath, action: "unchanged" };
+    }
+    await writeFile2(dstPath, srcContent);
+    await chmod(dstPath, 493);
+    return { path: destRelPath, action: "updated" };
+  }
+  await ensureParentDir(dstPath);
+  await writeFile2(dstPath, srcContent);
+  await chmod(dstPath, 493);
+  return { path: destRelPath, action: "created" };
+}
+var SCAFFOLD_PROJECT_YAML = `schema: aaac/project/0.1
+
+# Uncomment and configure to enable git hook governance:
+#
+# environments:
+#   git:
+#     hooks: [pre-commit, pre-push, post-commit]
+#   cursor:
+#     hooks_json: .cursor/hooks.json
+#
+# bindings:
+#   observability:
+#     event_mapping: ./bindings/observability.yaml
+#     recorder: aaac-observ
+#   hooks:
+#     # Each file declares gate commands per git hook; a non-zero exit
+#     # blocks the commit/push. Only hooks listed in environments.git.hooks
+#     # are materialized.
+#     - ./bindings/git.yaml
+`;
+
 export {
   SUPPORTED_SCHEMA_VERSIONS,
   SCHEMA_VERSION_PATTERN,
@@ -1470,6 +1919,7 @@ export {
   OptionSchema,
   ArtifactSlotValueSchema,
   OperationSchema,
+  BindingRefSchema,
   ComponentSchema,
   ComponentParseError,
   parseComponentString,
@@ -1484,12 +1934,24 @@ export {
   compileComponent,
   compileComponentAsync,
   compileComponentFile,
+  bindingsGenerator,
   cliGenerator,
   clientGenerator,
   handlerGenerator,
   runtimeGenerator,
   typesGenerator,
   generateAll,
-  writeGeneratedFiles
+  writeGeneratedFiles,
+  GOVERNANCE_LOCK_PATH,
+  loadInitConfig,
+  loadHookBindings,
+  parseCursorHooksFile,
+  serializeCursorHooksFile,
+  mergeCursorHooks,
+  readGovernanceLock,
+  materializeHooks,
+  unmaterializeHooks,
+  copyCLIBinary,
+  SCAFFOLD_PROJECT_YAML
 };
-//# sourceMappingURL=chunk-MWZFJ2VL.js.map
+//# sourceMappingURL=chunk-JWJLY3HJ.js.map