@aaac/contracts 0.1.15 → 0.1.16

package/dist/cli/index.js

@@ -13,8 +13,11 @@ import {
   loadHookBindings,
   loadInitConfig,
   materializeHooks,
+  mergeCursorHooks,
   parseComponentFile,
+  parseCursorHooksFile,
   readGovernanceLock,
+  serializeCursorHooksFile,
   unmaterializeHooks,
   validateComponent,
   writeGeneratedFiles
@@ -22,7 +25,7 @@ import {
 
 // src/cli/index.ts
 import { readFileSync } from "fs";
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname3, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 
 // ../../node_modules/commander/lib/error.js
@@ -3649,6 +3652,72 @@ var commandDefinitions = {
         }
       }
     ]
+  },
+  "init": {
+    "effects": {},
+    "options": [
+      {
+        "name": "project-yaml",
+        "schema": {
+          "type": "string"
+        }
+      },
+      {
+        "name": "binary-path",
+        "schema": {
+          "type": "string"
+        }
+      }
+    ]
+  },
+  "update": {
+    "effects": {},
+    "options": [
+      {
+        "name": "project-yaml",
+        "schema": {
+          "type": "string"
+        }
+      }
+    ]
+  },
+  "uninstall": {
+    "effects": {}
+  },
+  "install": {
+    "effects": {},
+    "options": [
+      {
+        "name": "global",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "dry-run",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "skip-cursor",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "skip-claude",
+        "schema": {
+          "type": "boolean"
+        }
+      },
+      {
+        "name": "skip-git",
+        "schema": {
+          "type": "boolean"
+        }
+      }
+    ]
   }
 };
 function deriveCommandPolicy(command_id, optionValues) {
@@ -3675,8 +3744,230 @@ function deriveCommandPolicy(command_id, optionValues) {
 }
 
 // src/generated/contract.ts
-var CONTRACT_YAML = "# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json\ncli_contracts: 0.1.0\n\ninfo:\n  title: AaaC CLI\n  version: 0.1.0\n  description: Agent as a Component \u2014 Contract compiler and code generator\n\ncommand_sets:\n  aaac:\n    summary: AaaC CLI \u2014 compile Component Contracts and generate adapters\n    executable: aaac\n    global_options:\n      - name: verbose\n        aliases: [v]\n        schema: { type: boolean }\n        description: Enable verbose output\n      - name: quiet\n        aliases: [q]\n        schema: { type: boolean }\n        description: Suppress non-essential output\n      - name: resume\n        schema: { type: string }\n        description: Resume from a previous memory_ref ID\n    commands:\n      compile:\n        summary: Compile a Component Contract YAML to Component IR\n        arguments:\n          - name: file\n            required: true\n            schema: { type: string }\n            description: Path to the Component Contract YAML file\n        options:\n          - name: output\n            aliases: [o]\n            schema: { type: string }\n            description: Output path for the compiled IR (JSON)\n        exits:\n          '0':\n            description: Compilation succeeded\n            stdout:\n              format: json\n              schema:\n                type: object\n                description: Component IR\n          '1':\n            description: Compilation failed (validation errors)\n            stderr:\n              format: text\n\n      generate:\n        summary: Generate adapters from a Component Contract\n        arguments:\n          - name: file\n            required: true\n            schema: { type: string }\n            description: Path to the Component Contract YAML file\n        options:\n          - name: output-dir\n            aliases: [o]\n            schema: { type: string }\n            description: Output directory for generated files\n          - name: targets\n            aliases: [t]\n            schema:\n              type: array\n              items:\n                type: string\n                enum: [library, cli, runtime, claude, openai]\n            description: Generation targets (defaults to projections in contract)\n          - name: dry-run\n            schema: { type: boolean }\n            description: Show what would be generated without writing files\n        effects:\n          filesystem: read_write\n        exits:\n          '0':\n            description: Generation succeeded\n            stdout:\n              format: text\n          '1':\n            description: Generation failed\n            stderr:\n              format: text\n\n      validate:\n        summary: Validate a Component Contract YAML\n        arguments:\n          - name: file\n            required: true\n            schema: { type: string }\n            description: Path to the Component Contract YAML file\n        options:\n          - name: strict\n            schema: { type: boolean }\n            description: Enable strict validation (check implementation refs)\n        exits:\n          '0':\n            description: Validation passed\n            stdout:\n              format: text\n          '1':\n            description: Validation failed\n            stderr:\n              format: text\n\n      introspect:\n        summary: Dump Component IR information\n        arguments:\n          - name: file\n            required: true\n            schema: { type: string }\n            description: Path to the Component Contract YAML file\n        options:\n          - name: format\n            aliases: [f]\n            schema:\n              type: string\n              enum: [json, yaml]\n            description: Output format (default yaml)\n        exits:\n          '0':\n            description: Success\n            stdout:\n              format: json\n              schema:\n                type: object\n                description: Component IR dump\n";
-var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "AaaC CLI",\n    "version": "0.1.0",\n    "description": "Agent as a Component \u2014 Contract compiler and code generator"\n  },\n  "command_sets": {\n    "aaac": {\n      "summary": "AaaC CLI \u2014 compile Component Contracts and generate adapters",\n      "executable": "aaac",\n      "global_options": [\n        {\n          "name": "verbose",\n          "aliases": [\n            "v"\n          ],\n          "schema": {\n            "type": "boolean"\n          },\n          "description": "Enable verbose output"\n        },\n        {\n          "name": "quiet",\n          "aliases": [\n            "q"\n          ],\n          "schema": {\n            "type": "boolean"\n          },\n          "description": "Suppress non-essential output"\n        },\n        {\n          "name": "resume",\n          "schema": {\n            "type": "string"\n          },\n          "description": "Resume from a previous memory_ref ID"\n        }\n      ],\n      "commands": {\n        "compile": {\n          "summary": "Compile a Component Contract YAML to Component IR",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "output",\n              "aliases": [\n                "o"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Output path for the compiled IR (JSON)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Compilation succeeded",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object",\n                  "description": "Component IR"\n                }\n              }\n            },\n            "1": {\n              "description": "Compilation failed (validation errors)",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "generate": {\n          "summary": "Generate adapters from a Component Contract",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "output-dir",\n              "aliases": [\n                "o"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Output directory for generated files"\n            },\n            {\n              "name": "targets",\n              "aliases": [\n                "t"\n              ],\n              "schema": {\n                "type": "array",\n                "items": {\n                  "type": "string",\n                  "enum": [\n                    "library",\n                    "cli",\n                    "runtime",\n                    "claude",\n                    "openai"\n                  ]\n                }\n              },\n              "description": "Generation targets (defaults to projections in contract)"\n            },\n            {\n              "name": "dry-run",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Show what would be generated without writing files"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Generation succeeded",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Generation failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "validate": {\n          "summary": "Validate a Component Contract YAML",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "strict",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Enable strict validation (check implementation refs)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Validation passed",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Validation failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "introspect": {\n          "summary": "Dump Component IR information",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "json",\n                  "yaml"\n                ]\n              },\n              "description": "Output format (default yaml)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Success",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object",\n                  "description": "Component IR dump"\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}';
+var CONTRACT_YAML = `# yaml-language-server: $schema=./node_modules/cli-contracts/schemas/cli-contract.schema.json
+cli_contracts: 0.1.0
+
+info:
+  title: AaaC CLI
+  version: 0.1.0
+  description: Agent as a Component \u2014 Contract compiler and code generator
+
+command_sets:
+  aaac:
+    summary: AaaC CLI \u2014 compile Component Contracts and generate adapters
+    executable: aaac
+    global_options:
+      - name: verbose
+        aliases: [v]
+        schema: { type: boolean }
+        description: Enable verbose output
+      - name: quiet
+        aliases: [q]
+        schema: { type: boolean }
+        description: Suppress non-essential output
+      - name: resume
+        schema: { type: string }
+        description: Resume from a previous memory_ref ID
+    commands:
+      compile:
+        summary: Compile a Component Contract YAML to Component IR
+        arguments:
+          - name: file
+            required: true
+            schema: { type: string }
+            description: Path to the Component Contract YAML file
+        options:
+          - name: output
+            aliases: [o]
+            schema: { type: string }
+            description: Output path for the compiled IR (JSON)
+        exits:
+          '0':
+            description: Compilation succeeded
+            stdout:
+              format: json
+              schema:
+                type: object
+                description: Component IR
+          '1':
+            description: Compilation failed (validation errors)
+            stderr:
+              format: text
+
+      generate:
+        summary: Generate adapters from a Component Contract
+        arguments:
+          - name: file
+            required: true
+            schema: { type: string }
+            description: Path to the Component Contract YAML file
+        options:
+          - name: output-dir
+            aliases: [o]
+            schema: { type: string }
+            description: Output directory for generated files
+          - name: targets
+            aliases: [t]
+            schema:
+              type: array
+              items:
+                type: string
+                enum: [library, cli, runtime, claude, openai]
+            description: Generation targets (defaults to projections in contract)
+          - name: dry-run
+            schema: { type: boolean }
+            description: Show what would be generated without writing files
+        effects:
+          filesystem: read_write
+        exits:
+          '0':
+            description: Generation succeeded
+            stdout:
+              format: text
+          '1':
+            description: Generation failed
+            stderr:
+              format: text
+
+      validate:
+        summary: Validate a Component Contract YAML
+        arguments:
+          - name: file
+            required: true
+            schema: { type: string }
+            description: Path to the Component Contract YAML file
+        options:
+          - name: strict
+            schema: { type: boolean }
+            description: Enable strict validation (check implementation refs)
+        exits:
+          '0':
+            description: Validation passed
+            stdout:
+              format: text
+          '1':
+            description: Validation failed
+            stderr:
+              format: text
+
+      introspect:
+        summary: Dump Component IR information
+        arguments:
+          - name: file
+            required: true
+            schema: { type: string }
+            description: Path to the Component Contract YAML file
+        options:
+          - name: format
+            aliases: [f]
+            schema:
+              type: string
+              enum: [json, yaml]
+            description: Output format (default yaml)
+        exits:
+          '0':
+            description: Success
+            stdout:
+              format: json
+              schema:
+                type: object
+                description: Component IR dump
+
+      init:
+        summary: Initialize a project \u2014 copy CLI binary, scaffold project.yaml, materialize git hooks
+        arguments:
+          - name: projectRoot
+            required: false
+            schema: { type: string }
+            description: "Project root directory (default: current directory)"
+        options:
+          - name: project-yaml
+            schema: { type: string }
+            description: Path to project.yaml relative to projectRoot (default project.yaml)
+          - name: binary-path
+            schema: { type: string }
+            description: "Path to the CLI binary to copy (default: process.argv[1]); for programmatic/test use"
+        effects:
+          filesystem: read_write
+        exits:
+          '0':
+            description: Initialization succeeded
+            stdout:
+              format: text
+          '1':
+            description: Initialization failed
+            stderr:
+              format: text
+
+      update:
+        summary: Re-read project.yaml and re-materialize git hooks
+        arguments:
+          - name: projectRoot
+            required: false
+            schema: { type: string }
+            description: "Project root directory (default: current directory)"
+        options:
+          - name: project-yaml
+            schema: { type: string }
+            description: Path to project.yaml relative to projectRoot (default project.yaml)
+        effects:
+          filesystem: read_write
+        exits:
+          '0':
+            description: Update succeeded
+            stdout:
+              format: text
+          '1':
+            description: Update failed
+            stderr:
+              format: text
+
+      uninstall:
+        summary: Remove all managed hook blocks recorded in governance-manifest.lock
+        arguments:
+          - name: projectRoot
+            required: false
+            schema: { type: string }
+            description: "Project root directory (default: current directory)"
+        effects:
+          filesystem: read_write
+        exits:
+          '0':
+            description: Uninstall succeeded
+            stdout:
+              format: text
+
+      install:
+        summary: Install user-global observability hooks (Cursor + Claude + Git) in one command \u2014 idempotent, non-destructive
+        options:
+          - name: global
+            schema: { type: boolean }
+            description: Install at user scope (~/.cursor, ~/.claude, git --global). Currently the only supported scope.
+          - name: dry-run
+            schema: { type: boolean }
+            description: Preview the changes without writing any files or git config
+          - name: skip-cursor
+            schema: { type: boolean }
+            description: Do not configure the Cursor user hooks
+          - name: skip-claude
+            schema: { type: boolean }
+            description: Do not configure the Claude Code user hooks
+          - name: skip-git
+            schema: { type: boolean }
+            description: Do not configure the global git hooks / core.hooksPath
+        effects:
+          filesystem: read_write
+        exits:
+          '0':
+            description: Install succeeded (or previewed with --dry-run)
+            stdout:
+              format: text
+          '1':
+            description: Install failed
+            stderr:
+              format: text
+`;
+var CONTRACT_JSON_STR = '{\n  "cli_contracts": "0.1.0",\n  "info": {\n    "title": "AaaC CLI",\n    "version": "0.1.0",\n    "description": "Agent as a Component \u2014 Contract compiler and code generator"\n  },\n  "command_sets": {\n    "aaac": {\n      "summary": "AaaC CLI \u2014 compile Component Contracts and generate adapters",\n      "executable": "aaac",\n      "global_options": [\n        {\n          "name": "verbose",\n          "aliases": [\n            "v"\n          ],\n          "schema": {\n            "type": "boolean"\n          },\n          "description": "Enable verbose output"\n        },\n        {\n          "name": "quiet",\n          "aliases": [\n            "q"\n          ],\n          "schema": {\n            "type": "boolean"\n          },\n          "description": "Suppress non-essential output"\n        },\n        {\n          "name": "resume",\n          "schema": {\n            "type": "string"\n          },\n          "description": "Resume from a previous memory_ref ID"\n        }\n      ],\n      "commands": {\n        "compile": {\n          "summary": "Compile a Component Contract YAML to Component IR",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "output",\n              "aliases": [\n                "o"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Output path for the compiled IR (JSON)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Compilation succeeded",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object",\n                  "description": "Component IR"\n                }\n              }\n            },\n            "1": {\n              "description": "Compilation failed (validation errors)",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "generate": {\n          "summary": "Generate adapters from a Component Contract",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "output-dir",\n              "aliases": [\n                "o"\n              ],\n              "schema": {\n                "type": "string"\n              },\n              "description": "Output directory for generated files"\n            },\n            {\n              "name": "targets",\n              "aliases": [\n                "t"\n              ],\n              "schema": {\n                "type": "array",\n                "items": {\n                  "type": "string",\n                  "enum": [\n                    "library",\n                    "cli",\n                    "runtime",\n                    "claude",\n                    "openai"\n                  ]\n                }\n              },\n              "description": "Generation targets (defaults to projections in contract)"\n            },\n            {\n              "name": "dry-run",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Show what would be generated without writing files"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Generation succeeded",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Generation failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "validate": {\n          "summary": "Validate a Component Contract YAML",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "strict",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Enable strict validation (check implementation refs)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Validation passed",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Validation failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "introspect": {\n          "summary": "Dump Component IR information",\n          "arguments": [\n            {\n              "name": "file",\n              "required": true,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the Component Contract YAML file"\n            }\n          ],\n          "options": [\n            {\n              "name": "format",\n              "aliases": [\n                "f"\n              ],\n              "schema": {\n                "type": "string",\n                "enum": [\n                  "json",\n                  "yaml"\n                ]\n              },\n              "description": "Output format (default yaml)"\n            }\n          ],\n          "exits": {\n            "0": {\n              "description": "Success",\n              "stdout": {\n                "format": "json",\n                "schema": {\n                  "type": "object",\n                  "description": "Component IR dump"\n                }\n              }\n            }\n          }\n        },\n        "init": {\n          "summary": "Initialize a project \u2014 copy CLI binary, scaffold project.yaml, materialize git hooks",\n          "arguments": [\n            {\n              "name": "projectRoot",\n              "required": false,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Project root directory (default: current directory)"\n            }\n          ],\n          "options": [\n            {\n              "name": "project-yaml",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to project.yaml relative to projectRoot (default project.yaml)"\n            },\n            {\n              "name": "binary-path",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to the CLI binary to copy (default: process.argv[1]); for programmatic/test use"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Initialization succeeded",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Initialization failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "update": {\n          "summary": "Re-read project.yaml and re-materialize git hooks",\n          "arguments": [\n            {\n              "name": "projectRoot",\n              "required": false,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Project root directory (default: current directory)"\n            }\n          ],\n          "options": [\n            {\n              "name": "project-yaml",\n              "schema": {\n                "type": "string"\n              },\n              "description": "Path to project.yaml relative to projectRoot (default project.yaml)"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Update succeeded",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Update failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "uninstall": {\n          "summary": "Remove all managed hook blocks recorded in governance-manifest.lock",\n          "arguments": [\n            {\n              "name": "projectRoot",\n              "required": false,\n              "schema": {\n                "type": "string"\n              },\n              "description": "Project root directory (default: current directory)"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Uninstall succeeded",\n              "stdout": {\n                "format": "text"\n              }\n            }\n          }\n        },\n        "install": {\n          "summary": "Install user-global observability hooks (Cursor + Claude + Git) in one command \u2014 idempotent, non-destructive",\n          "options": [\n            {\n              "name": "global",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Install at user scope (~/.cursor, ~/.claude, git --global). Currently the only supported scope."\n            },\n            {\n              "name": "dry-run",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Preview the changes without writing any files or git config"\n            },\n            {\n              "name": "skip-cursor",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Do not configure the Cursor user hooks"\n            },\n            {\n              "name": "skip-claude",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Do not configure the Claude Code user hooks"\n            },\n            {\n              "name": "skip-git",\n              "schema": {\n                "type": "boolean"\n              },\n              "description": "Do not configure the global git hooks / core.hooksPath"\n            }\n          ],\n          "effects": {\n            "filesystem": "read_write"\n          },\n          "exits": {\n            "0": {\n              "description": "Install succeeded (or previewed with --dry-run)",\n              "stdout": {\n                "format": "text"\n              }\n            },\n            "1": {\n              "description": "Install failed",\n              "stderr": {\n                "format": "text"\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n}';
 
 // src/generated/program.ts
 function createProgram(handlers2, version) {
@@ -3722,17 +4013,41 @@ 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) => {
+  program3.command("init").description("Initialize a project \u2014 copy CLI binary, scaffold project.yaml, 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)").option("--binary-path <value>", "Path to the CLI binary to copy (default: process.argv[1]); for programmatic/test use").action(async (projectRoot, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("init", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
     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) => {
+  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();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("update", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
     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);
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("uninstall", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.uninstall(projectRoot, {}, globalOpts);
+  });
+  program3.command("install").description("Install user-global observability hooks (Cursor + Claude + Git) in one command \u2014 idempotent, non-destructive").option("--global", "Install at user scope (~/.cursor, ~/.claude, git --global). Currently the only supported scope.").option("--dry-run", "Preview the changes without writing any files or git config").option("--skip-cursor", "Do not configure the Cursor user hooks").option("--skip-claude", "Do not configure the Claude Code user hooks").option("--skip-git", "Do not configure the global git hooks / core.hooksPath").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    if (globalOpts.introspect) {
+      const policy = deriveCommandPolicy("install", opts);
+      console.log(JSON.stringify(policy, null, 2));
+      return;
+    }
+    await handlers2.install(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) {
@@ -3751,7 +4066,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", "aaac.init", "aaac.update", "aaac.uninstall"]
+            commands: ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect", "aaac.init", "aaac.update", "aaac.uninstall", "aaac.install"]
           };
         }
         Object.assign(out, doc);
@@ -3768,7 +4083,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", "aaac.init", "aaac.update", "aaac.uninstall"]) {
+          for (const id of ["aaac.compile", "aaac.generate", "aaac.validate", "aaac.introspect", "aaac.init", "aaac.update", "aaac.uninstall", "aaac.install"]) {
             yamlLines.push("  - " + id);
           }
         }
@@ -3808,9 +4123,189 @@ function createProgram(handlers2, version) {
 }
 
 // src/cli/handlers.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { homedir } from "os";
+import { dirname as dirname2, join as join2, resolve } from "path";
+
+// src/cli/global-install.ts
+import { execFileSync } from "child_process";
 import { existsSync } from "fs";
-import { mkdir, writeFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var GLOBAL_RECORDER_CMD = "aaac-observ-global-record";
+var GLOBAL_CURSOR_HOOK_EVENTS = [
+  "sessionStart",
+  "sessionEnd",
+  "subagentStart",
+  "subagentStop",
+  "preToolUse",
+  "postToolUse",
+  "afterFileEdit",
+  "afterShellExecution"
+];
+function buildGlobalCursorEntries(recorder = GLOBAL_RECORDER_CMD) {
+  return GLOBAL_CURSOR_HOOK_EVENTS.map((event) => ({
+    event,
+    command: `${recorder} ${event} --source cursor-hook`
+  }));
+}
+function cursorHooksPath(home) {
+  return join(home, ".cursor", "hooks.json");
+}
+var GLOBAL_CLAUDE_HOOK_EVENTS = [
+  "SessionStart",
+  "PreToolUse",
+  "PostToolUse",
+  "Stop",
+  "SubagentStop"
+];
+function buildClaudeHookCommand(event, recorder = GLOBAL_RECORDER_CMD) {
+  return `${recorder} ${event} --source claude-hook`;
+}
+function claudeSettingsPath(home) {
+  return join(home, ".claude", "settings.json");
+}
+function parseClaudeSettings(raw) {
+  if (!raw || !raw.trim()) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function serializeClaudeSettings(settings) {
+  return JSON.stringify(settings, null, 2) + "\n";
+}
+function mergeClaudeSettings(existing, recorder = GLOBAL_RECORDER_CMD) {
+  const settings = { ...existing };
+  const hooks = {};
+  for (const [event, groups] of Object.entries(existing.hooks ?? {})) {
+    hooks[event] = groups.map((g) => ({ ...g, hooks: g.hooks.map((h) => ({ ...h })) }));
+  }
+  for (const event of GLOBAL_CLAUDE_HOOK_EVENTS) {
+    const command = buildClaudeHookCommand(event, recorder);
+    const groups = hooks[event] ?? [];
+    const already = groups.some((g) => g.hooks.some((h) => h.command === command));
+    if (!already) {
+      groups.push({ hooks: [{ type: "command", command }] });
+    }
+    hooks[event] = groups;
+  }
+  settings.hooks = hooks;
+  return settings;
+}
+var GLOBAL_GIT_HOOK_NAMES = [
+  "pre-commit",
+  "commit-msg",
+  "post-commit",
+  "pre-push"
+];
+function globalGitHooksDir(home) {
+  return join(home, ".aaac", "git-hooks");
+}
+function buildGlobalGitHookScript(recorder = GLOBAL_RECORDER_CMD) {
+  return [
+    "#!/bin/sh",
+    "# >>> aaac-observ:global-git-hook (do not edit) >>>",
+    "# Records promotion events from ANY repo, then chains to the repo-local hook.",
+    'hook_name="$(basename "$0")"',
+    `${recorder} "$hook_name" --source git-hook >/dev/null 2>&1 || true`,
+    'repo_root="$(git rev-parse --show-toplevel 2>/dev/null)"',
+    'if [ -n "$repo_root" ] && [ -x "$repo_root/.git/hooks/$hook_name" ]; then',
+    '  exec "$repo_root/.git/hooks/$hook_name" "$@"',
+    "fi",
+    "exit 0",
+    "# <<< aaac-observ:global-git-hook <<<",
+    ""
+  ].join("\n");
+}
+var defaultGitConfigIO = {
+  get(key) {
+    try {
+      const out = execFileSync("git", ["config", "--global", "--get", key], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+      const trimmed = out.trim();
+      return trimmed.length > 0 ? trimmed : void 0;
+    } catch {
+      return void 0;
+    }
+  },
+  set(key, value) {
+    execFileSync("git", ["config", "--global", key, value], { stdio: "ignore" });
+  }
+};
+async function readIfExists(path2) {
+  if (!existsSync(path2)) return void 0;
+  return readFile(path2, "utf8");
+}
+async function materializeFile(target, path2, existing, next, dryRun, mode) {
+  let action;
+  if (existing === void 0) action = "create";
+  else if (existing === next) action = "unchanged";
+  else action = "update";
+  if (!dryRun && action !== "unchanged") {
+    await mkdir(dirname(path2), { recursive: true });
+    await writeFile(path2, next, "utf8");
+    if (mode !== void 0) await chmod(path2, mode);
+  }
+  return { target, path: path2, action };
+}
+async function installGlobalHooks(opts) {
+  const {
+    home,
+    recorder = GLOBAL_RECORDER_CMD,
+    dryRun = false,
+    cursor = true,
+    claude = true,
+    git = true,
+    gitConfig = defaultGitConfigIO
+  } = opts;
+  const actions = [];
+  if (cursor) {
+    const path2 = cursorHooksPath(home);
+    const existingRaw = await readIfExists(path2);
+    const merged = mergeCursorHooks(parseCursorHooksFile(existingRaw), buildGlobalCursorEntries(recorder));
+    const next = serializeCursorHooksFile(merged);
+    actions.push(await materializeFile("cursor", path2, existingRaw, next, dryRun));
+  }
+  if (claude) {
+    const path2 = claudeSettingsPath(home);
+    const existingRaw = await readIfExists(path2);
+    const merged = mergeClaudeSettings(parseClaudeSettings(existingRaw), recorder);
+    const next = serializeClaudeSettings(merged);
+    actions.push(await materializeFile("claude", path2, existingRaw, next, dryRun));
+  }
+  if (git) {
+    const hooksDir = globalGitHooksDir(home);
+    const script = buildGlobalGitHookScript(recorder);
+    for (const name of GLOBAL_GIT_HOOK_NAMES) {
+      const path2 = join(hooksDir, name);
+      const existingRaw = await readIfExists(path2);
+      actions.push(await materializeFile("git", path2, existingRaw, script, dryRun, 493));
+    }
+    const current = gitConfig.get("core.hooksPath");
+    if (current === hooksDir) {
+      actions.push({ target: "git", path: "core.hooksPath", action: "unchanged" });
+    } else if (current && current.length > 0) {
+      actions.push({
+        target: "git",
+        path: "core.hooksPath",
+        action: "skip",
+        note: `core.hooksPath already set to ${current}; leave it and source ${hooksDir} from your hooks, or unset to let aaac manage it`
+      });
+    } else {
+      if (!dryRun) gitConfig.set("core.hooksPath", hooksDir);
+      actions.push({ target: "git", path: "core.hooksPath", action: "create" });
+    }
+  }
+  return actions;
+}
+
+// src/cli/handlers.ts
 import { stringify as stringifyYaml } from "yaml";
 function formatError(err, file) {
   if (err instanceof ComponentParseError) {
@@ -3842,7 +4337,7 @@ function resolveComponentPath(file) {
   return resolve(file);
 }
 function defaultOutputDir(componentPath) {
-  return join(dirname(componentPath), "generated");
+  return join2(dirname2(componentPath), "generated");
 }
 function buildIntrospectionDump(ir) {
   const operations = {};
@@ -3877,7 +4372,7 @@ 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(resolve(options.output), `${json}
 `, "utf-8");
       if (!parentOpts.quiet) {
         process.stdout.write(`Wrote IR to ${resolve(options.output)}
@@ -3895,7 +4390,7 @@ async function resolveEmbeddedDslData(ir, componentPath) {
   if (!ir.embeddedDslDir || !ir.implementation) {
     return void 0;
   }
-  const implPath = resolve(dirname(componentPath), ir.implementation);
+  const implPath = resolve(dirname2(componentPath), ir.implementation);
   const { resolve: resolveDsl } = await import("agent-contracts");
   const dslResult = await resolveDsl(implPath);
   return dslResult.data;
@@ -3939,10 +4434,10 @@ var handleGenerate = async (file, options, parentOpts) => {
           }
         }
         for (const generated of embedded) {
-          const embeddedDir = resolve(dirname(componentPath), generated.targetDir);
+          const embeddedDir = resolve(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)
 `
           );
         }
@@ -3951,10 +4446,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 = resolve(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) {
@@ -3984,7 +4479,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 });
@@ -4020,22 +4515,22 @@ var DEFAULT_PROJECT_YAML = "project.yaml";
 var handleInit = async (projectRoot, options, parentOpts) => {
   const root = resolve(projectRoot ?? ".");
   const quiet = Boolean(parentOpts.quiet);
-  const projectYamlPath = join(root, options.projectYaml ?? DEFAULT_PROJECT_YAML);
+  const projectYamlPath = join2(root, options.projectYaml ?? DEFAULT_PROJECT_YAML);
   const srcBinary = resolve(options.binaryPath ?? process.argv[1]);
   const binaryResult = await copyCLIBinary(srcBinary, root);
   if (!quiet && binaryResult.action !== "unchanged") {
     process.stdout.write(`  ${binaryResult.action}: ${binaryResult.path}
 `);
   }
-  if (!existsSync(projectYamlPath)) {
-    await writeFile(projectYamlPath, SCAFFOLD_PROJECT_YAML, "utf8");
+  if (!existsSync2(projectYamlPath)) {
+    await writeFile2(projectYamlPath, SCAFFOLD_PROJECT_YAML, "utf8");
     if (!quiet) {
       process.stdout.write(`  created: ${DEFAULT_PROJECT_YAML}
 `);
     }
   }
-  const gitDir = join(root, ".git");
-  if (!existsSync(gitDir)) {
+  const gitDir = join2(root, ".git");
+  if (!existsSync2(gitDir)) {
     process.stderr.write(
       `Warning: .git/ not found in ${root}; skipping hook materialization
 `
@@ -4093,14 +4588,14 @@ var handleInit = async (projectRoot, options, parentOpts) => {
 var handleUpdate = async (projectRoot, options, parentOpts) => {
   const root = resolve(projectRoot ?? ".");
   const quiet = Boolean(parentOpts.quiet);
-  const projectYamlPath = join(root, options.projectYaml ?? DEFAULT_PROJECT_YAML);
-  if (!existsSync(projectYamlPath)) {
+  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 = join(root, ".git");
-  if (!existsSync(gitDir)) {
+  const gitDir = join2(root, ".git");
+  if (!existsSync2(gitDir)) {
     process.stderr.write(
       `Warning: .git/ not found in ${root}; skipping hook materialization
 `
@@ -4146,7 +4641,7 @@ var handleUninstall = async (projectRoot, _options, parentOpts) => {
   if (!lock || lock.entries.length === 0) {
     if (!quiet) {
       process.stdout.write(
-        `Nothing to uninstall (no governance lock found at ${join(root, GOVERNANCE_LOCK_PATH)})
+        `Nothing to uninstall (no governance lock found at ${join2(root, GOVERNANCE_LOCK_PATH)})
 `
       );
     }
@@ -4158,6 +4653,38 @@ var handleUninstall = async (projectRoot, _options, parentOpts) => {
 `);
   }
 };
+var handleInstall = async (options, parentOpts) => {
+  const quiet = Boolean(parentOpts.quiet);
+  const dryRun = Boolean(options.dryRun);
+  const home = homedir();
+  if (!home) {
+    fail("Error: could not resolve home directory ($HOME)");
+  }
+  let actions;
+  try {
+    actions = await installGlobalHooks({
+      home,
+      dryRun,
+      cursor: !options.skipCursor,
+      claude: !options.skipClaude,
+      git: !options.skipGit
+    });
+  } catch (err) {
+    fail(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!quiet) {
+    const prefix = dryRun ? "[dry-run] " : "";
+    for (const a of actions) {
+      const note = a.note ? ` \u2014 ${a.note}` : "";
+      process.stdout.write(`  ${prefix}${a.action}: [${a.target}] ${a.path}${note}
+`);
+    }
+    process.stdout.write(
+      `${dryRun ? "Previewed" : "Installed"} user-global observability hooks (Cursor + Claude + Git)
+`
+    );
+  }
+};
 var handlers = {
   compile: handleCompile,
   generate: handleGenerate,
@@ -4165,11 +4692,12 @@ var handlers = {
   introspect: handleIntrospect,
   init: handleInit,
   update: handleUpdate,
-  uninstall: handleUninstall
+  uninstall: handleUninstall,
+  install: handleInstall
 };
 
 // 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")
 );