@intentius/chant 0.1.7 → 0.1.9

package/src/cli/main.test.ts

@@ -198,6 +198,7 @@ describe("resolveCommand", () => {
       watch: false,
       verbose: false,
       help: false,
+      live: false,
       ...overrides,
     };
   }

package/src/cli/main.ts

@@ -36,6 +36,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     help: false,
     profile: undefined,
     report: undefined,
+    live: false,
   };
 
   let i = 0;
@@ -64,6 +65,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.profile = args[++i];
     } else if (arg === "--report") {
       result.report = true;
+    } else if (arg === "--live") {
+      result.live = true;
     } else if (!arg.startsWith("-")) {
       if (!result.command) {
         result.command = arg;
@@ -114,6 +117,7 @@ State:
   state snapshot <env>  Query API, save metadata to orphan branch
   state show <env>      Show latest state snapshot
   state diff <env>      Compare current build against last snapshot
+                        --live: query cloud now and detect drift
   state log [env]       History of state snapshots
 
 Lexicon development:

package/src/cli/mcp/tools/search.ts

@@ -52,7 +52,12 @@ export function createSearchHandler(
 
     for (const plugin of candidates) {
       const resources = plugin.mcpResources?.() ?? [];
-      const catalog = resources.find((r) => r.uri === "resource-catalog");
+      // Catalog URIs were unscoped ("resource-catalog") before lexicon
+      // namespacing landed; new lexicons emit "<lexicon>:resource-catalog"
+      // to avoid cross-lexicon collision. Support both.
+      const catalog = resources.find(
+        (r) => r.uri === "resource-catalog" || r.uri.endsWith(":resource-catalog"),
+      );
       if (!catalog) continue;
 
       let entries: CatalogEntry[];

package/src/cli/registry.ts

@@ -20,6 +20,7 @@ export interface ParsedArgs {
   help: boolean;
   profile?: string;
   report?: boolean;
+  live: boolean;
 }
 
 /**

package/src/lexicon-plugin-helpers.ts

@@ -61,15 +61,18 @@ export function createSkillsLoader(
 /**
  * Create an MCP diff tool contribution for a lexicon.
  *
- * All lexicons (except Azure) expose an identical "diff" tool that compares
- * current build output against previous output using the lexicon's serializer.
+ * All lexicons (except Azure) expose an identical-shape "diff" tool that
+ * compares current build output against previous output using the lexicon's
+ * serializer. The tool name is namespaced by `lexiconName` (e.g. `gcp:diff`)
+ * so multiple lexicons loaded together don't collide on the same tool key.
  */
 export function createDiffTool(
   serializer: Serializer,
   description: string,
+  lexiconName: string,
 ): McpToolContribution {
   return {
-    name: "diff",
+    name: `${lexiconName}:diff`,
     description,
     inputSchema: {
       type: "object" as const,
@@ -96,21 +99,26 @@ export function createDiffTool(
 /**
  * Create an MCP resource that serves the lexicon's meta.json as a catalog.
  *
- * Most lexicons expose a "resource-catalog" resource with identical structure.
+ * Most lexicons expose a "resource-catalog" resource with identical
+ * structure. The URI is namespaced by `lexiconName` (e.g.
+ * `gcp:resource-catalog`) so multiple lexicons loaded together don't
+ * collide on the same resource key.
  *
  * @param importMetaUrl — The plugin's import.meta.url (used to locate generated JSON)
  * @param name — Display name (e.g. "AWS Resource Catalog")
  * @param description — Resource description
  * @param lexiconJsonFile — Filename of the generated lexicon JSON (e.g. "lexicon-aws.json")
+ * @param lexiconName — Short lexicon name (e.g. "aws", "gcp"). Becomes the URI prefix.
  */
 export function createCatalogResource(
   importMetaUrl: string,
   name: string,
   description: string,
   lexiconJsonFile: string,
+  lexiconName: string,
 ): McpResourceContribution {
   return {
-    uri: "resource-catalog",
+    uri: `${lexiconName}:resource-catalog`,
     name,
     description,
     mimeType: "application/json",

package/src/lexicon.ts

@@ -195,12 +195,48 @@ export interface LexiconPlugin {
   mcpResources?(): McpResourceContribution[];
 
   // State
-  /** Query deployed resources and return API metadata. Opt-in. */
+  /**
+   * Query deployed resources and return API metadata. Opt-in.
+   *
+   * Use this when each chant entity has a 1:1 cloud equivalent — e.g. an
+   * AWS CFN resource, a K8s object, an ARM resource, a Temporal namespace.
+   *
+   * `entities` carries the chant-side entity declarations for this lexicon,
+   * keyed by chant entity name (e.g. the export name from a `*.ts` file).
+   * Implementations that need to map cloud-side names back to chant entity
+   * names (e.g. Temporal — server-side namespace `prod` ↔ chant entity `ns`
+   * declared with `name: "prod"`) read this; implementations that already
+   * have name parity (e.g. AWS CloudFormation logical IDs == chant entity
+   * names) can ignore it.
+   *
+   * `entityNames` is preserved as a convenience for the simple case.
+   */
   describeResources?(options: {
     environment: string;
     buildOutput: string;
     entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   }): Promise<Record<string, ResourceMetadata>>;
+
+  /**
+   * List runtime artifacts in the given environment. Opt-in.
+   *
+   * Use this for lexicons whose chant entities describe *authoring*
+   * primitives rather than 1:1 cloud resources — e.g. Helm (charts vs
+   * releases), Docker (Compose vs running containers), Flyway (migration
+   * scripts vs applied migrations). The contract is context-keyed: given an
+   * environment, list all artifacts visible there. There is no `declared`
+   * comparison axis — `state diff --live` reports added/removed/changed
+   * between snapshots, not vs. declared.
+   *
+   * `entities` is passed for cases where the lexicon needs to know what
+   * was declared in order to enumerate (e.g. Flyway needs the declared
+   * `Flyway::Environment` entities to know which DBs to query).
+   */
+  listArtifacts?(options: {
+    environment: string;
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  }): Promise<Record<string, ArtifactMetadata>>;
 }
 
 /**
@@ -219,6 +255,26 @@ export interface ResourceMetadata {
   attributes?: Record<string, unknown>;
 }
 
+/**
+ * Metadata about a runtime artifact, returned by listArtifacts. Same shape
+ * as ResourceMetadata; the conceptual distinction is whether the lexicon's
+ * chant entities have 1:1 runtime equivalents (resources) or whether the
+ * runtime artifacts are created by tooling outside chant's entity model
+ * (artifacts — e.g. Helm releases, Docker containers, Flyway migrations).
+ */
+export interface ArtifactMetadata {
+  /** Artifact type (e.g. Helm::Release, Docker::Container) */
+  type: string;
+  /** Server-side identifier */
+  physicalId?: string;
+  /** Provider-specific status string */
+  status: string;
+  /** ISO timestamp of last update */
+  lastUpdated?: string;
+  /** Provider-specific properties */
+  attributes?: Record<string, unknown>;
+}
+
 /**
  * Type guard to check if a value is a LexiconPlugin.
  * Checks for required lifecycle methods in addition to name/serializer.

package/src/lint/config.test.ts

@@ -641,4 +641,25 @@ describe("loadConfig", () => {
     const config = loadConfig(subDir);
     expect(config).toEqual(DEFAULT_CONFIG);
   });
+
+  test("accepts ChantConfig-shape nested lint key in chant.config.json", () => {
+    const configPath = join(TEST_DIR, "chant.config.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        lexicons: ["aws"],
+        lint: {
+          rules: {
+            "test-rule": "error",
+            "noisy-rule": "off",
+          },
+        },
+      }),
+    );
+
+    const config = loadConfig(TEST_DIR);
+
+    expect(config.rules?.["test-rule"]).toBe("error");
+    expect(config.rules?.["noisy-rule"]).toBe("off");
+  });
 });

package/src/lint/config.ts

@@ -223,18 +223,34 @@ function loadConfigFile(configPath: string, visited: Set<string> = new Set()): L
     throw new Error(`Failed to read config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
   }
 
-  let config: LintConfig;
+  let raw: unknown;
   try {
-    config = JSON.parse(content);
+    raw = JSON.parse(content);
   } catch (err) {
     throw new Error(`Failed to parse config file ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
   }
 
   // Validate config structure
-  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error(`Invalid config file ${configPath}: must be an object`);
   }
 
+  // Accept both shapes: lint fields at top level (legacy) OR nested under a
+  // "lint" key (matches chant.config.ts ChantConfig shape). When the JSON has
+  // both a top-level "rules"/"extends"/etc AND a "lint": {...}, prefer the
+  // nested one — that matches the explicit ChantConfig contract.
+  const rawObj = raw as Record<string, unknown>;
+  let config: LintConfig;
+  if (
+    rawObj.lint &&
+    typeof rawObj.lint === "object" &&
+    !Array.isArray(rawObj.lint)
+  ) {
+    config = rawObj.lint as LintConfig;
+  } else {
+    config = rawObj as LintConfig;
+  }
+
   // Validate with Zod schema
   const parseResult = LintConfigSchema.safeParse(config);
   if (!parseResult.success) {

package/src/lint/rule-loader.test.ts

@@ -64,4 +64,32 @@ describe("rule-loader", () => {
     // Clean up
     rmSync(join(RULES_DIR, "my-rule.test.ts"));
   });
+
+  test("walks up to find .chant/rules/ when invoked from a sub-stack dir", async () => {
+    // Project layout: TEST_DIR (root, has .chant/rules/) -> src/east/.
+    const subStack = join(TEST_DIR, "src", "east");
+    mkdirSync(subStack, { recursive: true });
+    writeFileSync(join(TEST_DIR, "package.json"), `{ "name": "fixture" }`);
+    try {
+      const rules = await loadLocalRules(subStack);
+      expect(rules).toHaveLength(1);
+      expect(rules[0].id).toBe("LOCAL001");
+    } finally {
+      rmSync(join(TEST_DIR, "src"), { recursive: true });
+      rmSync(join(TEST_DIR, "package.json"));
+    }
+  });
+
+  test("stops at the nearest package.json — does not climb into an unrelated parent", async () => {
+    const innerProject = join(TEST_DIR, "inner-proj");
+    const innerSubDir = join(innerProject, "src");
+    mkdirSync(innerSubDir, { recursive: true });
+    writeFileSync(join(innerProject, "package.json"), `{ "name": "inner" }`);
+    try {
+      const rules = await loadLocalRules(innerSubDir);
+      expect(rules).toHaveLength(0);
+    } finally {
+      rmSync(innerProject, { recursive: true });
+    }
+  });
 });

package/src/lint/rule-loader.ts

@@ -1,5 +1,5 @@
 import { readdirSync, existsSync } from "fs";
-import { join, resolve } from "path";
+import { dirname, join, resolve } from "path";
 import type { LintRule } from "./rule";
 
 /**
@@ -19,18 +19,51 @@ function isLintRule(value: unknown): value is LintRule {
 }
 
 /**
- * Load local lint rules from `.chant/rules/` directory.
+ * Walk up from `from` until a directory containing `.chant/rules/` is found,
+ * or until we hit the filesystem root or a non-project boundary (a directory
+ * with `package.json` but no `.chant/rules/` — that's the project root and
+ * we stop there even if no rules dir exists).
  *
- * Scans for `.ts` files, dynamically imports each, and collects
- * all exports that conform to the LintRule interface.
+ * Returns the absolute path to the discovered `.chant/rules/` directory, or
+ * null if none was found before we crossed the project root.
+ */
+function findRulesDir(from: string): string | null {
+  let cur = resolve(from);
+  while (true) {
+    const candidate = join(cur, ".chant", "rules");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    // Stop at the nearest project root (where package.json sits) — going
+    // above it would pick up rules belonging to an unrelated parent project.
+    if (existsSync(join(cur, "package.json"))) {
+      return null;
+    }
+    const parent = dirname(cur);
+    if (parent === cur) {
+      return null;
+    }
+    cur = parent;
+  }
+}
+
+/**
+ * Load local lint rules from `.chant/rules/`.
+ *
+ * Scans for `.ts` files in the nearest `.chant/rules/` directory found by
+ * walking up from `projectDir` (stopping at the closest `package.json` to
+ * avoid leaking into unrelated parent projects). Dynamically imports each
+ * file and collects all exports that conform to the LintRule interface.
  *
- * @param projectDir - Root directory of the project
- * @returns Array of LintRule objects found in `.chant/rules/`
+ * @param projectDir - Directory the lint command was invoked against. May be
+ *                     a sub-stack of a larger project — the rules dir is
+ *                     resolved by walking up.
+ * @returns Array of LintRule objects found in the discovered `.chant/rules/`.
  */
 export async function loadLocalRules(projectDir: string): Promise<LintRule[]> {
-  const rulesDir = join(projectDir, ".chant", "rules");
+  const rulesDir = findRulesDir(projectDir);
 
-  if (!existsSync(rulesDir)) {
+  if (rulesDir === null) {
     return [];
   }
 

package/src/op/types.ts

@@ -46,6 +46,19 @@ export interface ActivityStep {
    * Default: "fastIdempotent"
    */
   profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+  /**
+   * Surface this activity's return value as a workflow search attribute.
+   *
+   * The serializer captures the awaited result into a temporary, then emits
+   * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
+   * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
+   * from a stateDiff activity).
+   *
+   * `from` is a dot-path into the return value (e.g. `"drifted"` for
+   * `{ drifted: boolean }`); when omitted, the whole return value is
+   * stringified.
+   */
+  outcomeAttribute?: { name: string; from?: string };
 }
 
 export interface GateStep {

package/src/state/digest.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "vitest";
+import { computeBuildDigest, diffDigests, hashProps } from "./digest";
+import type { BuildResult } from "../build";
+import type { BuildDigest } from "./types";
+
+function makeBuildResult(entitiesByLexicon: Record<string, Array<{ name: string; type: string; props: unknown }>>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, list] of Object.entries(entitiesByLexicon)) {
+    for (const item of list) {
+      entities.set(item.name, { lexicon, entityType: item.type, props: item.props });
+    }
+  }
+  return {
+    outputs: new Map(Object.keys(entitiesByLexicon).map((l) => [l, "{}"])),
+    entities,
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: {
+      lexicons: Object.keys(entitiesByLexicon),
+      outputs: {},
+      deployOrder: Object.keys(entitiesByLexicon),
+    },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("hashProps", () => {
+  test("produces the same hash for identical props", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ a: 1, b: 2 }));
+  });
+
+  test("is order-independent (sorted JSON serialization)", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ b: 2, a: 1 }));
+  });
+
+  test("produces different hashes for different props", () => {
+    expect(hashProps({ a: 1 })).not.toBe(hashProps({ a: 2 }));
+  });
+});
+
+describe("computeBuildDigest", () => {
+  test("emits one entry per entity with type, lexicon, and propsHash", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "bucket", type: "AWS::S3::Bucket", props: { name: "data" } }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["bucket"]).toMatchObject({
+      type: "AWS::S3::Bucket",
+      lexicon: "aws",
+      propsHash: expect.any(String),
+    });
+  });
+
+  test("missing props default to empty object", () => {
+    const buildResult = makeBuildResult({ aws: [{ name: "x", type: "T", props: undefined }] });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["x"].propsHash).toBe(hashProps({}));
+  });
+
+  test("mirrors the build manifest's deployOrder and outputs", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "b", type: "T", props: {} }],
+      gcp: [{ name: "g", type: "T", props: {} }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.deployOrder).toEqual(["aws", "gcp"]);
+    expect(digest.outputs).toEqual({});
+  });
+});
+
+describe("diffDigests", () => {
+  function makeDigest(resources: Record<string, string>): BuildDigest {
+    const out: BuildDigest["resources"] = {};
+    for (const [name, propsHash] of Object.entries(resources)) {
+      out[name] = { type: "T", lexicon: "aws", propsHash };
+    }
+    return { resources: out, dependencies: {}, outputs: {}, deployOrder: [] };
+  }
+
+  test("no previous digest → everything is added", () => {
+    const result = diffDigests(makeDigest({ a: "x", b: "y" }), undefined);
+    expect(result.added).toEqual(["a", "b"]);
+    expect(result.removed).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("identical digests → all unchanged", () => {
+    const d = makeDigest({ a: "x" });
+    const result = diffDigests(d, d);
+    expect(result.unchanged).toEqual(["a"]);
+    expect(result.added).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.removed).toEqual([]);
+  });
+
+  test("different propsHash → changed", () => {
+    const result = diffDigests(makeDigest({ a: "x2" }), makeDigest({ a: "x1" }));
+    expect(result.changed).toEqual(["a"]);
+  });
+
+  test("resource gone from current → removed", () => {
+    const result = diffDigests(makeDigest({}), makeDigest({ a: "x" }));
+    expect(result.removed).toEqual(["a"]);
+  });
+
+  test("mixed: added + removed + changed + unchanged", () => {
+    const previous = makeDigest({ a: "x1", b: "y", c: "z" });
+    const current = makeDigest({ a: "x2", b: "y", d: "w" });
+    const result = diffDigests(current, previous);
+    expect(result.added.sort()).toEqual(["d"]);
+    expect(result.changed.sort()).toEqual(["a"]);
+    expect(result.unchanged.sort()).toEqual(["b"]);
+    expect(result.removed.sort()).toEqual(["c"]);
+  });
+});