@aaac/contracts 0.1.10 → 0.1.12

package/dist/cli/index.js

@@ -10,11 +10,11 @@ import {
   parseComponentFile,
   validateComponent,
   writeGeneratedFiles
-} from "../chunk-PJ6U3DZV.js";
+} from "../chunk-MWZFJ2VL.js";
 
 // src/cli/index.ts
 import { readFileSync } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname3, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 
 // ../../node_modules/commander/lib/error.js
@@ -3714,6 +3714,18 @@ function createProgram(handlers2, version) {
     }
     await handlers2.introspect(file, opts, globalOpts);
   });
+  program3.command("init").description("Initialize a project: copy the CLI binary, scaffold project.yaml, and materialize git hooks").argument("[projectRoot]", "Project root directory (default: current directory)").option("--project-yaml <value>", "Path to project.yaml relative to projectRoot (default: project.yaml)").action(async (projectRoot, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    await handlers2.init(projectRoot, opts, globalOpts);
+  });
+  program3.command("update").description("Re-read project.yaml and re-materialize git hooks").argument("[projectRoot]", "Project root directory (default: current directory)").option("--project-yaml <value>", "Path to project.yaml relative to projectRoot (default: project.yaml)").action(async (projectRoot, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    await handlers2.update(projectRoot, opts, globalOpts);
+  });
+  program3.command("uninstall").description("Remove all managed hook blocks recorded in governance-manifest.lock").argument("[projectRoot]", "Project root directory (default: current directory)").action(async (projectRoot, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    await handlers2.uninstall(projectRoot, opts, globalOpts);
+  });
   program3.command("extract").description("Extract contract specification for this CLI tool.").argument("[commands...]", "Command IDs to extract. Use dot notation.").option("-a, --all", "Extract all commands.", false).option("--include-meta", "Include extraction metadata.", true).option("-F, --format <format>", "Output format (yaml or json).", "yaml").action(async (commands, opts, cmd) => {
     if (commands.length === 0 && !opts.all) {
       process.stderr.write(JSON.stringify({ code: "INVALID_ARGS", message: "Specify command IDs or use --all" }) + "\n");
@@ -3731,7 +3743,7 @@ function createProgram(handlers2, version) {
             type: "cli-contracts/extract",
             extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
             specVersion: doc.cli_contracts ?? "0.1.0",
-            commands: ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect"]
+            commands: ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect", "aaac.init", "aaac.update", "aaac.uninstall"]
           };
         }
         Object.assign(out, doc);
@@ -3748,7 +3760,7 @@ function createProgram(handlers2, version) {
           yamlLines.push("extractedAt: " + (/* @__PURE__ */ new Date()).toISOString());
           yamlLines.push("spec_version: " + (doc.cli_contracts ?? "0.1.0"));
           yamlLines.push("commands:");
-          for (const id of ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect"]) {
+          for (const id of ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect", "aaac.init", "aaac.update", "aaac.uninstall"]) {
             yamlLines.push("  - " + id);
           }
         }
@@ -3788,9 +3800,260 @@ function createProgram(handlers2, version) {
 }
 
 // src/cli/handlers.ts
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
 import { stringify as stringifyYaml } from "yaml";
+
+// src/cli/governance.ts
+import { createHash } from "crypto";
+import { existsSync } from "fs";
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { parse as parseYaml } from "yaml";
+import { z } 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 EnvironmentsSchema = z.object({
+  git: z.object({ hooks: z.array(z.string()).optional() }).optional(),
+  cursor: z.object({ hooks_json: z.string().optional() }).optional()
+}).optional();
+var BindingsObservabilitySchema = z.object({
+  event_mapping: z.string().optional(),
+  recorder: z.string().optional()
+}).optional();
+var BindingsSchema = z.object({
+  observability: BindingsObservabilitySchema
+}).optional();
+var InitProjectConfigSchema = z.object({
+  environments: EnvironmentsSchema,
+  bindings: BindingsSchema
+});
+async function loadInitConfig(configPath) {
+  const absPath = resolve(configPath);
+  const raw = await readFile(absPath, "utf8");
+  const parsed = parseYaml(raw);
+  return InitProjectConfigSchema.parse(parsed ?? {});
+}
+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 mergeCursorHooks(existing, newEntries) {
+  const byCommand = /* @__PURE__ */ new Map();
+  for (const entry of existing) byCommand.set(entry.command, entry);
+  for (const entry of newEntries) byCommand.set(entry.command, entry);
+  return Array.from(byCommand.values());
+}
+function removeCursorHooks(existing, commands) {
+  const removeSet = new Set(commands);
+  return existing.filter((entry) => !removeSet.has(entry.command));
+}
+function buildDefaultCursorHooks(recorder) {
+  return [
+    { event: "beforeSubmitPrompt", command: `${recorder} beforeSubmitPrompt` },
+    { event: "afterShellExecution", command: `${recorder} afterShellExecution` }
+  ];
+}
+async function ensureParentDir(filePath) {
+  await mkdir(dirname(filePath), { recursive: true });
+}
+async function readTextFileIfExists(filePath) {
+  if (!existsSync(filePath)) return void 0;
+  return readFile(filePath, "utf8");
+}
+async function writeGovernanceLock(projectRoot, entries) {
+  const lockPath = join(projectRoot, GOVERNANCE_LOCK_PATH);
+  const lock = {
+    materialized_at: (/* @__PURE__ */ new Date()).toISOString(),
+    entries
+  };
+  await ensureParentDir(lockPath);
+  await writeFile(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  return GOVERNANCE_LOCK_PATH;
+}
+async function readGovernanceLock(projectRoot) {
+  const lockPath = join(projectRoot, GOVERNANCE_LOCK_PATH);
+  if (!existsSync(lockPath)) return void 0;
+  const raw = await readFile(lockPath, "utf8");
+  if (!raw.trim()) return void 0;
+  return JSON.parse(raw);
+}
+async function materializeHooks(options) {
+  const projectRoot = resolve(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 = join(".git/hooks", hookName);
+      const absPath = join(projectRoot, relPath);
+      const blockContent = `exec ${recorder} ${hookName} "$@"`;
+      const existing = await readTextFileIfExists(absPath) ?? "";
+      const updated = injectManagedBlock(existing, blockContent);
+      let action = "unchanged";
+      if (!existsSync(absPath)) {
+        action = "created";
+      } else if (updated !== existing) {
+        action = "updated";
+      }
+      if (action !== "unchanged") {
+        await ensureParentDir(absPath);
+        await writeFile(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 ? resolve(projectRoot, rawHooksJsonValue) : join(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 = existingRaw ? JSON.parse(existingRaw) : [];
+    const merged = mergeCursorHooks(existing, newEntries);
+    const serialized = JSON.stringify(merged, null, 2) + "\n";
+    let action = "unchanged";
+    if (!existsSync(hooksJsonPath)) {
+      action = "created";
+    } else if (serialized !== existingRaw) {
+      action = "updated";
+    }
+    if (action !== "unchanged") {
+      await ensureParentDir(hooksJsonPath);
+      await writeFile(hooksJsonPath, serialized, "utf8");
+    }
+    result.materialized.push({ path: relPath, action });
+    result.lockEntries.push({ path: relPath, type: "cursor-hook" });
+  }
+  if (result.lockEntries.length > 0) {
+    const lockExisted = existsSync(join(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 = resolve(projectRoot);
+  for (const entry of lockEntries) {
+    if (entry.type === "generated") {
+      const absPath = join(root, entry.path);
+      if (existsSync(absPath)) {
+        await writeFile(absPath, "", "utf8");
+      }
+      continue;
+    }
+    if (entry.type === "git-hook") {
+      const absPath = join(root, entry.path);
+      const existing = await readTextFileIfExists(absPath);
+      if (existing === void 0) continue;
+      const updated = removeManagedBlock(existing);
+      await writeFile(absPath, updated, "utf8");
+      continue;
+    }
+    if (entry.type === "cursor-hook") {
+      const absPath = join(root, entry.path);
+      const existingRaw = await readTextFileIfExists(absPath);
+      if (existingRaw === void 0) continue;
+      const existing = JSON.parse(existingRaw);
+      const commandsToRemove = buildDefaultCursorHooks(DEFAULT_RECORDER).map((h) => h.command);
+      const updated = removeCursorHooks(existing, commandsToRemove);
+      await writeFile(
+        absPath,
+        updated.length === 0 ? "[]\n" : JSON.stringify(updated, null, 2) + "\n",
+        "utf8"
+      );
+    }
+  }
+  const lockPath = join(root, GOVERNANCE_LOCK_PATH);
+  if (existsSync(lockPath)) {
+    await writeFile(lockPath, "", "utf8");
+  }
+}
+async function copyCLIBinary(srcPath, projectRoot, destRelPath = DEFAULT_BINARY_DEST) {
+  const dstPath = join(projectRoot, destRelPath);
+  const srcContent = await readFile(srcPath);
+  const srcHash = createHash("sha256").update(srcContent).digest("hex");
+  if (existsSync(dstPath)) {
+    const dstContent = await readFile(dstPath);
+    const dstHash = createHash("sha256").update(dstContent).digest("hex");
+    if (srcHash === dstHash) {
+      return { path: destRelPath, action: "unchanged" };
+    }
+    await writeFile(dstPath, srcContent);
+    await chmod(dstPath, 493);
+    return { path: destRelPath, action: "updated" };
+  }
+  await ensureParentDir(dstPath);
+  await writeFile(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
+`;
+
+// src/cli/handlers.ts
 function formatError(err, file) {
   if (err instanceof ComponentParseError) {
     return err.message;
@@ -3818,10 +4081,10 @@ function resolveComponentPath(file) {
   if (!file) {
     fail("Error: component file path is required");
   }
-  return resolve(file);
+  return resolve2(file);
 }
 function defaultOutputDir(componentPath) {
-  return join(dirname(componentPath), "generated");
+  return join2(dirname2(componentPath), "generated");
 }
 function buildIntrospectionDump(ir) {
   const operations = {};
@@ -3856,10 +4119,10 @@ var handleCompile = async (file, options, parentOpts) => {
     const ir = await compileComponentFile(componentPath);
     const json = JSON.stringify(ir, null, 2);
     if (options.output) {
-      await writeFile(resolve(options.output), `${json}
+      await writeFile2(resolve2(options.output), `${json}
 `, "utf-8");
       if (!parentOpts.quiet) {
-        process.stdout.write(`Wrote IR to ${resolve(options.output)}
+        process.stdout.write(`Wrote IR to ${resolve2(options.output)}
 `);
       }
       return;
@@ -3874,7 +4137,7 @@ async function resolveEmbeddedDslData(ir, componentPath) {
   if (!ir.embeddedDslDir || !ir.implementation) {
     return void 0;
   }
-  const implPath = resolve(dirname(componentPath), ir.implementation);
+  const implPath = resolve2(dirname2(componentPath), ir.implementation);
   const { resolve: resolveDsl } = await import("agent-contracts");
   const dslResult = await resolveDsl(implPath);
   return dslResult.data;
@@ -3893,7 +4156,7 @@ function splitGeneratedFiles(files) {
 }
 var handleGenerate = async (file, options, parentOpts) => {
   const componentPath = resolveComponentPath(file);
-  const outputDir = resolve(options.outputDir ?? defaultOutputDir(componentPath));
+  const outputDir = resolve2(options.outputDir ?? defaultOutputDir(componentPath));
   const dryRun = Boolean(options.dryRun);
   try {
     const ir = await compileComponentFile(componentPath);
@@ -3918,10 +4181,10 @@ var handleGenerate = async (file, options, parentOpts) => {
           }
         }
         for (const generated of embedded) {
-          const embeddedDir = resolve(dirname(componentPath), generated.targetDir);
+          const embeddedDir = resolve2(dirname2(componentPath), generated.targetDir);
           const action = generated.overwrite ? "write" : "create";
           process.stdout.write(
-            `  ${action}: ${join(embeddedDir, generated.path)} (embedded DSL)
+            `  ${action}: ${join2(embeddedDir, generated.path)} (embedded DSL)
 `
           );
         }
@@ -3930,10 +4193,10 @@ var handleGenerate = async (file, options, parentOpts) => {
     }
     const result = await writeGeneratedFiles(main, outputDir);
     for (const generated of embedded) {
-      const embeddedDir = resolve(dirname(componentPath), generated.targetDir);
-      await mkdir(embeddedDir, { recursive: true });
-      await writeFile(join(embeddedDir, generated.path), generated.content, "utf-8");
-      result.written.push(join(generated.targetDir, generated.path));
+      const embeddedDir = resolve2(dirname2(componentPath), generated.targetDir);
+      await mkdir2(embeddedDir, { recursive: true });
+      await writeFile2(join2(embeddedDir, generated.path), generated.content, "utf-8");
+      result.written.push(join2(generated.targetDir, generated.path));
     }
     if (!parentOpts.quiet) {
       if (result.written.length > 0) {
@@ -3963,7 +4226,7 @@ var handleGenerate = async (file, options, parentOpts) => {
 };
 var handleValidate = async (file, options, parentOpts) => {
   const componentPath = resolveComponentPath(file);
-  const basePath = dirname(componentPath);
+  const basePath = dirname2(componentPath);
   try {
     const dsl = await parseComponentFile(componentPath);
     const ir = compileComponent(dsl, { basePath });
@@ -3995,17 +4258,156 @@ var handleIntrospect = async (file, options, _parentOpts) => {
     fail(formatError(err, componentPath));
   }
 };
+var DEFAULT_PROJECT_YAML = "project.yaml";
+var handleInit = async (projectRoot, options, parentOpts) => {
+  const root = resolve2(projectRoot ?? ".");
+  const quiet = Boolean(parentOpts.quiet);
+  const projectYamlPath = join2(root, options.projectYaml ?? DEFAULT_PROJECT_YAML);
+  const srcBinary = resolve2(options.binaryPath ?? process.argv[1]);
+  const binaryResult = await copyCLIBinary(srcBinary, root);
+  if (!quiet && binaryResult.action !== "unchanged") {
+    process.stdout.write(`  ${binaryResult.action}: ${binaryResult.path}
+`);
+  }
+  if (!existsSync2(projectYamlPath)) {
+    await writeFile2(projectYamlPath, SCAFFOLD_PROJECT_YAML, "utf8");
+    if (!quiet) {
+      process.stdout.write(`  created: ${DEFAULT_PROJECT_YAML}
+`);
+    }
+  }
+  const gitDir = join2(root, ".git");
+  if (!existsSync2(gitDir)) {
+    process.stderr.write(
+      `Warning: .git/ not found in ${root}; skipping hook materialization
+`
+    );
+    if (!quiet) {
+      process.stdout.write(`Initialized project at ${root}
+`);
+    }
+    return;
+  }
+  let config;
+  try {
+    config = await loadInitConfig(projectYamlPath);
+  } catch (err) {
+    process.stderr.write(
+      `Warning: Could not parse ${DEFAULT_PROJECT_YAML}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    if (!quiet) {
+      process.stdout.write(`Initialized project at ${root}
+`);
+    }
+    return;
+  }
+  if (!config.environments) {
+    if (!quiet) {
+      process.stdout.write(
+        `  no environments configured in ${DEFAULT_PROJECT_YAML}; skipping hooks
+`
+      );
+      process.stdout.write(`Initialized project at ${root}
+`);
+    }
+    return;
+  }
+  const result = await materializeHooks({
+    projectRoot: root,
+    environments: config.environments,
+    observabilityBinding: config.bindings?.observability
+  });
+  if (!quiet) {
+    for (const m of result.materialized) {
+      if (m.action !== "unchanged") {
+        process.stdout.write(`  ${m.action}: ${m.path}
+`);
+      }
+    }
+    process.stdout.write(`Initialized project at ${root}
+`);
+  }
+};
+var handleUpdate = async (projectRoot, options, parentOpts) => {
+  const root = resolve2(projectRoot ?? ".");
+  const quiet = Boolean(parentOpts.quiet);
+  const projectYamlPath = join2(root, options.projectYaml ?? DEFAULT_PROJECT_YAML);
+  if (!existsSync2(projectYamlPath)) {
+    fail(
+      `Error: ${DEFAULT_PROJECT_YAML} not found at ${root}. Run 'aaac init' first.`
+    );
+  }
+  const gitDir = join2(root, ".git");
+  if (!existsSync2(gitDir)) {
+    process.stderr.write(
+      `Warning: .git/ not found in ${root}; skipping hook materialization
+`
+    );
+    return;
+  }
+  let config;
+  try {
+    config = await loadInitConfig(projectYamlPath);
+  } catch (err) {
+    fail(
+      `Error: Could not parse ${DEFAULT_PROJECT_YAML}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!config.environments) {
+    if (!quiet) {
+      process.stdout.write(`No environments configured in ${DEFAULT_PROJECT_YAML}
+`);
+    }
+    return;
+  }
+  const result = await materializeHooks({
+    projectRoot: root,
+    environments: config.environments,
+    observabilityBinding: config.bindings?.observability
+  });
+  if (!quiet) {
+    for (const m of result.materialized) {
+      process.stdout.write(`  ${m.action}: ${m.path}
+`);
+    }
+    process.stdout.write(`Updated hooks at ${root}
+`);
+  }
+};
+var handleUninstall = async (projectRoot, _options, parentOpts) => {
+  const root = resolve2(projectRoot ?? ".");
+  const quiet = Boolean(parentOpts.quiet);
+  const lock = await readGovernanceLock(root);
+  if (!lock || lock.entries.length === 0) {
+    if (!quiet) {
+      process.stdout.write(
+        `Nothing to uninstall (no governance lock found at ${join2(root, GOVERNANCE_LOCK_PATH)})
+`
+      );
+    }
+    return;
+  }
+  await unmaterializeHooks(root, lock.entries);
+  if (!quiet) {
+    process.stdout.write(`Uninstalled governance hooks from ${root}
+`);
+  }
+};
 var handlers = {
   compile: handleCompile,
   generate: handleGenerate,
   validate: handleValidate,
-  introspect: handleIntrospect
+  introspect: handleIntrospect,
+  init: handleInit,
+  update: handleUpdate,
+  uninstall: handleUninstall
 };
 
 // src/cli/index.ts
-var __dirname = dirname2(fileURLToPath(import.meta.url));
+var __dirname = dirname3(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync(resolve2(__dirname, "../../package.json"), "utf8")
+  readFileSync(resolve3(__dirname, "../../package.json"), "utf8")
 );
 var program2 = createProgram(handlers, pkg.version);
 await program2.parseAsync();