@intentius/chant 0.52.1 → 0.52.2

package/src/cli/handlers/misc.ts

@@ -5,6 +5,9 @@ import { loadChantConfig } from "../../config";
 import { resolve } from "path";
 import { auditCommand, printAuditResult, type AuditFormat, type AuditTier, type AuditFailOn } from "../commands/audit";
 import type { ReportTheme } from "../../audit/report-html";
+import { AGENT_RUNTIMES, AGENT_SCOPES, type AgentRuntime, type AgentScope } from "../../agents/types";
+import { registeredProjectRoots } from "../../agents/discover";
+import { homedir } from "os";
 import type { ResourceSelector } from "../../lexicon";
 import { formatError, formatSuccess, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
@@ -23,6 +26,44 @@ const AUDIT_FORMATS: AuditFormat[] = ["stylish", "json", "sarif", "markdown", "h
 const AUDIT_TIERS: AuditTier[] = ["merge-worthy", "all"];
 const AUDIT_FAIL_ON: AuditFailOn[] = ["merge-worthy", "warning", "none"];
 
+/**
+ * Parse `--scope system,user,project`. Returns `undefined` (meaning "all") when
+ * the flag is absent, or an Error the caller reports — an unrecognized scope is
+ * rejected rather than ignored, since silently scanning more than the user
+ * asked for is exactly the surprise this command exists to prevent.
+ */
+function parseScopes(raw: string | undefined): readonly AgentScope[] | undefined | Error {
+  if (!raw) return undefined;
+  const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const bad = parts.filter((p) => !AGENT_SCOPES.includes(p as AgentScope));
+  if (bad.length > 0) return new Error(`Invalid --scope: ${bad.join(", ")}. Expected one or more of ${AGENT_SCOPES.join(", ")}.`);
+  return parts.length > 0 ? (parts as AgentScope[]) : undefined;
+}
+
+/** Parse `--runtime claude,codex,...`. Same contract as {@link parseScopes}. */
+function parseRuntimes(raw: string | undefined): readonly AgentRuntime[] | undefined | Error {
+  if (!raw) return undefined;
+  const parts = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const bad = parts.filter((p) => !AGENT_RUNTIMES.includes(p as AgentRuntime));
+  if (bad.length > 0) return new Error(`Invalid --runtime: ${bad.join(", ")}. Expected one or more of ${AGENT_RUNTIMES.join(", ")}.`);
+  return parts.length > 0 ? (parts as AgentRuntime[]) : undefined;
+}
+
+/**
+ * Project roots for an `--agents` run.
+ *
+ * Default: the path argument alone. With `--all-projects`, every project root
+ * the harness has registered, *unioned* with the path argument rather than
+ * replacing it — a flag that silently discarded an argument the user typed
+ * would be the wrong kind of surprise, and a cwd that isn't registered yet is
+ * still a project the user is plainly interested in.
+ */
+function resolveProjectRoots(args: { path: string; allProjects?: boolean }): string[] {
+  const named = resolve(args.path);
+  if (!args.allProjects) return [named];
+  return [...new Set([...registeredProjectRoots(homedir()), named])].sort();
+}
+
 export async function runAudit(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
@@ -42,6 +83,37 @@ export async function runAudit(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // `--agents` switches the subject from a repo to this machine's agent
+  // configuration. Same formats, tiers, and fail-on policy — a different thing
+  // being audited, not a different report.
+  if (args.agents) {
+    const scopes = parseScopes(args.scope);
+    if (scopes instanceof Error) {
+      console.error(formatError({ message: scopes.message }));
+      return 1;
+    }
+    const runtimes = parseRuntimes(args.runtime);
+    if (runtimes instanceof Error) {
+      console.error(formatError({ message: runtimes.message }));
+      return 1;
+    }
+    const { auditAgentsCommand } = await import("../commands/audit-agents");
+    const result = auditAgentsCommand({
+      format,
+      tier,
+      failOn,
+      scopes,
+      runtimes,
+      projectRoots: resolveProjectRoots(args),
+      output: args.output,
+      toolVersion: CHANT_VERSION,
+    });
+    if (result.error) console.error(formatError({ message: result.error }));
+    else if (result.wroteTo) console.log(formatSuccess(`Report written to ${result.wroteTo}`));
+    else console.log(result.output);
+    return result.exitCode;
+  }
+
   // HTML report customization: --template <file> (full override) + --theme <file> (JSON knobs).
   let template: string | undefined;
   let theme: ReportTheme | undefined;
@@ -171,6 +243,45 @@ export async function runDescribe(ctx: CommandContext): Promise<number> {
 export async function runImport(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
 
+  // `--agents` (#chant audit --agents' other half): the source is this
+  // machine's agent configuration rather than a template file, so there is
+  // nothing to detect — the flag names the subject, like `--kustomize` below
+  // names the lexicon.
+  if (args.agents) {
+    const scopes = parseScopes(args.scope);
+    if (scopes instanceof Error) {
+      console.error(formatError({ message: scopes.message }));
+      return 1;
+    }
+    const runtimes = parseRuntimes(args.runtime);
+    if (runtimes instanceof Error) {
+      console.error(formatError({ message: runtimes.message }));
+      return 1;
+    }
+    const { importAgentsCommand } = await import("../commands/import-agents");
+    const result = await importAgentsCommand({
+      lexicon: args.lexicon,
+      output: args.output,
+      force: args.force,
+      scopes,
+      runtimes,
+      projectRoots: resolveProjectRoots(args),
+    });
+    for (const warning of result.warnings) console.warn(formatWarning({ message: warning }));
+    if (!result.success) {
+      console.error(formatError({ message: result.error ?? "Import failed." }));
+      return 1;
+    }
+    console.log(
+      formatSuccess(
+        `Re-expressed ${result.summary.mapped} resource${result.summary.mapped === 1 ? "" : "s"} ` +
+          `from ${result.summary.discovered} agent config${result.summary.discovered === 1 ? "" : "s"}:`,
+      ),
+    );
+    for (const file of result.generatedFiles) console.log(`  ${file}`);
+    return 0;
+  }
+
   // `--kustomize <dir>` (#1548): render the overlay and import the output
   // through the k8s template parser — the flag NAMES the lexicon, so no JSON
   // detection. `kustomize build`, falling back to kubectl's vendored

package/src/cli/main.ts

@@ -48,6 +48,8 @@ import type { LexiconPlugin } from "../lexicon";
  */
 const BOOLEAN_FLAGS = new Set([
   "--help",
+  "--agents",
+  "--all-projects",
   "--force",
   "--fix",
   "--watch",
@@ -254,6 +256,14 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.env = args[++i];
     } else if (arg === "--tier") {
       result.tier = args[++i];
+    } else if (arg === "--agents") {
+      result.agents = true;
+    } else if (arg === "--scope") {
+      result.scope = args[++i];
+    } else if (arg === "--all-projects") {
+      result.allProjects = true;
+    } else if (arg === "--runtime") {
+      result.runtime = args[++i];
     } else if (arg === "--fail-on") {
       result.failOn = args[++i];
     } else if (arg === "--theme") {
@@ -438,10 +448,17 @@ Commands:
                         bundle tree, otherwise JSON path→content on stdout)
   vendor                Pull pinned, checksummed patterns into your repo
   import                Import external template into TypeScript
+                        (--agents re-expresses this machine's agent config as
+                         chant code instead of reading a template file)
   audit [path|url]      Audit a repo's CI YAML for security issues
                         (--format stylish|json|sarif|markdown|html, -o <file>,
                          --tier merge-worthy|all, --fail-on merge-worthy|warning|none,
                          --template <file> / --theme <file> for the html report)
+                        --agents audits this machine's agent configuration —
+                        instruction files, MCP servers, skills, plugins,
+                        permissions — instead of a repository
+                        (--scope system,user,project, --runtime claude,codex,...,
+                         --all-projects)
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
   carve advise          Read-only Terraform peelability advisor: rank which

package/src/cli/registry.ts

@@ -158,6 +158,21 @@ export interface ParsedArgs {
   includeDependents?: boolean;
   /** `chant audit --tier merge-worthy|all` */
   tier?: string;
+  /**
+   * `chant audit --agents` / `chant import --agents` — switch the subject from
+   * a repo's pipeline YAML to the agent configuration installed on this
+   * machine (skills, MCP servers, instruction files, permissions).
+   */
+  agents?: boolean;
+  /** `--agents --scope system,user,project` — which scopes to scan (default all). */
+  scope?: string;
+  /** `--agents --runtime claude,codex,...` — which agent harnesses to scan (default all). */
+  runtime?: string;
+  /**
+   * `--agents --all-projects` — scan every project root the harness has
+   * registered in `~/.claude.json`, not just the path argument.
+   */
+  allProjects?: boolean;
   /** `chant audit --fail-on merge-worthy|warning|none` */
   failOn?: string;
   /** `chant audit --theme <file>` — JSON theme knobs for the HTML report */

package/src/lexicon.ts

@@ -5,6 +5,7 @@ import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
 import type { TemplateParser, TemplateIR } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
+import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
@@ -714,6 +715,17 @@ export interface LexiconPlugin {
   /** Return a generator for converting IR to TypeScript */
   templateGenerator?(): TypeScriptGenerator;
 
+  /**
+   * Re-express local agent configuration (skills, MCP servers, instruction
+   * files) discovered by `chant audit --agents` as this lexicon's resources.
+   *
+   * Implement this when the lexicon has types that model an agent's workload —
+   * fountain's `Agent`/`Environment` are the motivating case. Core does the
+   * harness-neutral discovery; the mapping onto concrete resource types is the
+   * lexicon's call, for the same reason `templateParser` is.
+   */
+  agentConfigImporter?(): AgentConfigImporter;
+
   /** Return skills provided by this lexicon */
   skills?(): SkillDefinition[];
 

package/src/terraform/adopt-state.ts

@@ -19,13 +19,13 @@
  */
 
 import {
-  AWS_CARVE_TYPES,
   AWS_LEXICON_IMPORT,
   awsCarveType,
   applyAwsMapper,
   applyAwsFold,
   unmappedFoldAttrs,
 } from "./aws-resources";
+import { canCarveEmit, carveEmitTypes } from "./tier-map";
 import type { StateResource } from "./state";
 
 /** The core subpath the emitted source reads build parameters from. */
@@ -70,14 +70,17 @@ export interface AdoptedSource {
   folded: FoldedContribution[];
 }
 
-/** Is this Terraform type adoptable from state (has a native constructor)? */
+/**
+ * Is this Terraform type adoptable from state (has a native constructor)? The
+ * same table gates the live path, so both are the shared `canCarveEmit`.
+ */
 export function canAdoptFromState(tfType: string): boolean {
-  return awsCarveType(tfType) !== undefined;
+  return canCarveEmit(tfType);
 }
 
 /** Terraform types that can currently be adopted from state, for user-facing hints. */
 export function supportedStateAdoptionTypes(): string[] {
-  return AWS_CARVE_TYPES.map((t) => t.tfType).sort();
+  return carveEmitTypes();
 }
 
 /** Marker for a prop whose value is a `params.<name>` reference, not a literal. */

package/src/terraform/aws-resources.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { AWS_CARVE_TYPES, AWS_FOLD_MAPPERS, awsCarveType, applyAwsMapper, applyAwsFold } from "./aws-resources";
-import { TIER_MAP, FOLDS_INTO, IDENTITY_ATTR } from "./tier-map";
+import { TIER_MAP, FOLDS_INTO, IDENTITY_ATTR, canBridge, canCarveEmit, carveEmitTypes } from "./tier-map";
 import { canAdoptFromState } from "./adopt-state";
 
 describe("AWS carve-out table", () => {
@@ -13,6 +13,29 @@ describe("AWS carve-out table", () => {
     for (const t of emitAws) expect(canAdoptFromState(t)).toBe(true);
   });
 
+  test("the emit gate is narrower than the tier map, which also ranks k8s (#2015)", () => {
+    // `carve advise` bands kubernetes types; emit has no path for them, so the
+    // gate both emit paths share must refuse them.
+    expect(TIER_MAP.kubernetes_config_map).toBeDefined();
+    expect(canCarveEmit("kubernetes_config_map")).toBe(false);
+    expect(canCarveEmit("kubernetes_manifest")).toBe(false);
+    expect(canCarveEmit("random_pet")).toBe(false);
+    expect(canCarveEmit("aws_s3_bucket")).toBe(true);
+    expect(carveEmitTypes()).toEqual(AWS_CARVE_TYPES.map((t) => t.tfType).sort());
+    // State adoption and live emit gate on the same table.
+    for (const t of carveEmitTypes()) expect(canAdoptFromState(t)).toBe(true);
+  });
+
+  test("canBridge rejects a dotted identity attribute (#2015)", () => {
+    // A data source body is flat `attr = value`; a dotted path is not HCL.
+    expect(IDENTITY_ATTR.kubernetes_manifest).toContain(".");
+    expect(canBridge("kubernetes_manifest")).toBe(false);
+    expect(canBridge("aws_s3_bucket")).toBe(true);
+    // No identity entry at all is fine — the bridge writes a TODO comment.
+    expect(canBridge("random_pet")).toBe(true);
+    for (const t of AWS_CARVE_TYPES) expect(canBridge(t.tfType)).toBe(true);
+  });
+
   test("covers the common carve targets across families", () => {
     const types = new Set(AWS_CARVE_TYPES.map((t) => t.tfType));
     for (const t of [

package/src/terraform/bridge.test.ts

@@ -51,6 +51,18 @@ describe("generateBridge — inbound (data-source rewrite)", () => {
     );
   });
 
+  test("never renders a dotted identity attribute into the data body (#2015)", () => {
+    const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
+    const dotted = new Map<string, CarvedIdentity>([
+      ["aws_s3_bucket.assets", { attr: "manifest.metadata.name", value: "demo-config" }],
+    ]);
+    const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], dotted);
+
+    // `manifest.metadata.name = "demo-config"` is not valid HCL.
+    expect(plan.dataSources[0].hcl).not.toContain("manifest.metadata.name =");
+    expect(plan.dataSources[0].hcl).toContain("# TODO: identify the resource");
+  });
+
   test("rewrites survivor references to the data source", () => {
     const report = boundaryReport(buildFixtureGraph(workedExample), "aws_s3_bucket.assets")!;
     const plan = generateBridge(report, [{ path: "api.tf", content: API_TF }], identities);

package/src/terraform/bridge.ts

@@ -81,8 +81,11 @@ function referenceRegex(address: string): RegExp {
 }
 
 function dataSourceHcl(type: string, name: string, identity: CarvedIdentity): string {
+  // A dotted attr is a path into nested blocks; `a.b.c = v` is not valid HCL,
+  // so it falls back to the TODO. `carve bridge` refuses such a type outright.
+  const flat = identity.attr !== undefined && !identity.attr.includes(".");
   const body =
-    identity.attr && identity.value !== undefined
+    flat && identity.value !== undefined
       ? `  ${identity.attr} = ${JSON.stringify(identity.value)}`
       : `  # TODO: identify the resource (its name/id was interpolated in the source)`;
   return `data ${JSON.stringify(type)} ${JSON.stringify(name)} {\n${body}\n}`;

package/src/terraform/tier-map.ts

@@ -12,7 +12,7 @@
  *   null   — no known native mapping (unsupported provider/type) → score 0
  */
 
-import { AWS_CARVE_TYPES } from "./aws-resources";
+import { AWS_CARVE_TYPES, awsCarveType } from "./aws-resources";
 
 export interface TierInfo {
   tier: 1 | 2 | 3;
@@ -110,3 +110,30 @@ export const IDENTITY_ATTR: Record<string, string> = {
 export function resolveTier(tfType: string): TierInfo | null {
   return TIER_MAP[tfType] ?? null;
 }
+
+/**
+ * Can `chant carve emit` produce chant source for this type? Narrower than
+ * `resolveTier`: the tier map also ranks the kubernetes types, which advise
+ * bands but no emit path can adopt (#999, blocked on the provider seam #2016).
+ * Both emit paths — `--state` and `--env` — gate on this, so a type either
+ * command refuses is refused by the other with the same message.
+ */
+export function canCarveEmit(tfType: string): boolean {
+  return awsCarveType(tfType) !== undefined;
+}
+
+/** The types `canCarveEmit` accepts, sorted, for user-facing hints. */
+export function carveEmitTypes(): string[] {
+  return AWS_CARVE_TYPES.map((t) => t.tfType).sort();
+}
+
+/**
+ * Can `chant carve bridge` render a Terraform `data` source for this type? A
+ * dotted `IDENTITY_ATTR` is a path into nested blocks, and a data source body
+ * is flat `attr = value` — `manifest.metadata.name = "x"` is not valid HCL.
+ * An absent entry is fine: the bridge writes a TODO comment for the identity.
+ */
+export function canBridge(tfType: string): boolean {
+  const attr = IDENTITY_ATTR[tfType];
+  return attr === undefined || !attr.includes(".");
+}

package/src/yaml.test.ts

@@ -484,3 +484,57 @@ describe("parseYAML — sibling keys after a nested block in a sequence item (#1
     });
   });
 });
+
+// #2013 — a colon opens a mapping only when whitespace or the end of the line
+// follows it (YAML 1.2 §7.4.2). The item/key disambiguation used to accept a
+// colon anywhere, which turned a bare URL in a sequence into a single-key
+// object and made the CRD-schema check reject a string list the emitter here
+// had written itself.
+describe("parseYAML — a colon without following space is not a mapping (#2013)", () => {
+  test("a bare URL in a sequence is a string", () => {
+    expect(parseYAML("sourceRepos:\n- https://github.com/INTENTIUS/behold\n")).toEqual({
+      sourceRepos: ["https://github.com/INTENTIUS/behold"],
+    });
+  });
+
+  test("an AppProject's sourceRepos round-trips through emit and parse", () => {
+    const repos = ["https://github.com/INTENTIUS/behold", "ssh://git@github.com:22/INTENTIUS/behold.git"];
+    expect(parseYAML(`spec:${emitYAML({ sourceRepos: repos }, 1)}\n`)).toEqual({ spec: { sourceRepos: repos } });
+  });
+
+  test("a real `- key: value` item is still a mapping", () => {
+    expect(parseYAML("items:\n- name: x\n  url: https://example.com/a\n")).toEqual({
+      items: [{ name: "x", url: "https://example.com/a" }],
+    });
+  });
+
+  test("a mapping item whose first value is a URL keeps its siblings", () => {
+    expect(parseYAML("sources:\n- repoURL: https://github.com/o/r\n  path: ./chart\n")).toEqual({
+      sources: [{ repoURL: "https://github.com/o/r", path: "./chart" }],
+    });
+  });
+
+  test("a quoted URL in a sequence still works", () => {
+    expect(parseYAML("sourceRepos:\n- 'https://github.com/o/r'\n- \"https://github.com/o/s\"\n")).toEqual({
+      sourceRepos: ["https://github.com/o/r", "https://github.com/o/s"],
+    });
+  });
+
+  test("`- key:value` with no space after the colon is a scalar, per the spec", () => {
+    expect(parseYAML("items:\n- key:value\n")).toEqual({ items: ["key:value"] });
+  });
+
+  test("`- key:` with nothing after the colon is still a mapping with a null value", () => {
+    expect(parseYAML("items:\n- key:\n")).toEqual({ items: [{ key: null }] });
+  });
+
+  test("a URL on a mapping line, not a sequence item, is unaffected", () => {
+    expect(parseYAML("url: https://example.com/a\n")).toEqual({ url: "https://example.com/a" });
+  });
+
+  test("a bare URL among mapping-shaped siblings inside one item", () => {
+    expect(parseYAML("items:\n- name: x\n  args:\n  - --endpoint\n  - https://example.com/a\n  image: nginx\n")).toEqual({
+      items: [{ name: "x", args: ["--endpoint", "https://example.com/a"], image: "nginx" }],
+    });
+  });
+});

package/src/yaml.ts

@@ -155,6 +155,27 @@ export interface ParseResult {
   endIndex: number;
 }
 
+/**
+ * `key: value` on a line of its own (`KEY_LINE`, capturing the indent) and the
+ * same after a sequence item's `- ` (`ITEM_KEY`).
+ *
+ * The lookahead is the rule both patterns used to miss: a `:` opens a mapping
+ * only when what follows it is whitespace or the end of the line, and a plain
+ * scalar may carry any other colon (YAML 1.2 §7.4.2). Written as `:\s*`, which
+ * matches zero whitespace, EVERY colon opened one — so a bare URL in a
+ * sequence,
+ *
+ *     sourceRepos:
+ *     - https://github.com/INTENTIUS/behold
+ *
+ * came back as `{ https: "//github.com/INTENTIUS/behold" }`, and the CRD-schema
+ * post-synth check (#1372) re-reading emitted YAML reported the string list
+ * this file's own emitter had just written as a list of objects (#2013). By the
+ * same rule `- key:value` is the scalar `"key:value"`, not a mapping.
+ */
+const KEY_LINE = /^(\s*)([^\s:][^:]*?):(?=\s|$)\s*(.*)$/;
+const ITEM_KEY = /^([^\s:][^:]*?):(?=\s|$)\s*(.*)$/;
+
 /**
  * Parse a YAML document (or JSON document) into a plain object.
  *
@@ -274,7 +295,7 @@ export function parseYAMLLines(
     if (indent < baseIndent) break; // Dedented — done with this block
     if (indent > baseIndent && startIndex > 0) break; // Unexpected indent
 
-    const keyMatch = line.match(/^(\s*)([^\s:][^:]*?):\s*(.*)$/);
+    const keyMatch = line.match(KEY_LINE);
     if (keyMatch) {
       const key = keyMatch[2].trim();
       const inlineValue = keyMatch[3].trim();
@@ -472,7 +493,7 @@ export function parseYAMLArray(
       const isQuotedScalar =
         (itemValue.startsWith('"') && itemValue.endsWith('"')) ||
         (itemValue.startsWith("'") && itemValue.endsWith("'"));
-      const kvMatch = !isQuotedScalar && itemValue.match(/^([^\s:][^:]*?):\s*(.*)$/);
+      const kvMatch = !isQuotedScalar && itemValue.match(ITEM_KEY);
       if (kvMatch) {
         const obj: Record<string, unknown> = {};
         obj[kvMatch[1].trim()] = parseArrayItemValue(kvMatch[2].trim(), lines, i, indent + 2);
@@ -506,7 +527,7 @@ export function parseYAMLArray(
           const ni = nextLine.search(/\S/);
           if (ni < nextIndent) break;
           if (ni > nextIndent) break; // belongs to a nested block already consumed
-          const nextKV = nextLine.match(/^(\s*)([^\s:][^:]*?):\s*(.*)$/);
+          const nextKV = nextLine.match(KEY_LINE);
           if (nextKV) {
             const nextVal = nextKV[3].trim();
             obj[nextKV[2].trim()] = parseArrayItemValue(nextVal, lines, j, ni);