@intentius/chant 0.52.1 → 0.53.0

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

@@ -23,7 +23,7 @@ import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
 import { runCarveEmit } from "./handlers/carve-emit";
 import { runCarveBridge } from "./handlers/carve-bridge";
 import { runCarveApply } from "./handlers/carve-apply";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
 import { runGraph } from "./handlers/graph";
@@ -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,16 +448,25 @@ 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
-                        --from <tf-dir>   resources are cheap to carve into native chant
+  carve advise          Read-only peelability advisor: rank which resources
+                        --from <dir>      are cheap to carve into native chant
                         (--json, --report <path>). Emits nothing, changes nothing.
-                        Needs @cdktf/hcl2json (npm install -D @cdktf/hcl2json).
+                        --from a Terraform dir needs @cdktf/hcl2json
+                        (npm install -D @cdktf/hcl2json); --from a CDK cloud
+                        assembly (cdk.out) needs nothing and ranks constructs.
   carve emit            Adopt a selected TF resource into chant source + report
                         --from <tf-dir>   its boundary. --state <tfstate> adopts offline
                         --select <addr>   (recommended for TF-managed resources); --env
@@ -539,6 +558,9 @@ Lifecycle (alias: lc):
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle whoami <env>    Who chant would act as in each configured lexicon,
+                            and what that principal is scoped to — read-only,
+                            before anything acts (--json, --strict)
   lifecycle teardown <env>  Plan what deleting the environment would remove —
                             marker-scoped (this project's stack + env); --yes
                             executes the plan (production-like names also need
@@ -629,7 +651,8 @@ Options:
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts
-  --strict              Escalate needs-review/validation to errors (migrate)
+  --strict              Escalate needs-review/validation to errors (migrate);
+                        exit nonzero on an unresolved identity (lifecycle whoami)
   --validate            Run external validator (glci/glab) after migrate
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
@@ -865,6 +888,7 @@ const registry: CommandDef[] = [
   { name: "lifecycle rollback", handler: runLifecycleRollback },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
+  { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
 

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/identity.test.ts

@@ -0,0 +1,199 @@
+import { describe, test, expect } from "vitest";
+import {
+  describeIdentities,
+  identityRowFor,
+  identityStatusText,
+  isUnresolvedIdentity,
+  redactCredentialMaterial,
+  redactIdentityRow,
+  REDACTED,
+  type IdentityPlugin,
+} from "./identity";
+
+describe("the identity tri-state (#1982)", () => {
+  test("a lexicon with no describeIdentity is not-reported, never an empty identity", async () => {
+    const rows = await describeIdentities([{ name: "github" }], { environment: "prod" }, {});
+    expect(rows).toEqual([{ lexicon: "github", status: "not-reported" }]);
+    expect(rows[0].identity).toBeUndefined();
+    expect(identityStatusText(rows[0])).toContain("not reported");
+  });
+
+  test("a resolved identity carries principal, scope, source and endpoint", async () => {
+    const plugin: IdentityPlugin = {
+      name: "aws",
+      describeIdentity: async () => ({
+        identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+        scope: "491500000000 us-east-1",
+        source: "env AWS_ACCESS_KEY_ID",
+        endpoint: "https://sts.us-east-1.amazonaws.com/",
+      }),
+    };
+    const [row] = await describeIdentities([plugin], { environment: "prod" }, {});
+    expect(row).toEqual({
+      lexicon: "aws",
+      status: "reported",
+      identity: "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      scope: "491500000000 us-east-1",
+      source: "env AWS_ACCESS_KEY_ID",
+      endpoint: "https://sts.us-east-1.amazonaws.com/",
+    });
+  });
+
+  test("no credentials and could-not-determine are distinguishable answers", async () => {
+    const rows = await describeIdentities(
+      [
+        { name: "aws", describeIdentity: async () => ({ unresolved: { reason: "no-credentials" } }) },
+        {
+          name: "k8s",
+          describeIdentity: async () => ({ unresolved: { reason: "read-failed", detail: "connection refused" } }),
+        },
+      ],
+      { environment: "prod" },
+      {},
+    );
+    expect(rows[0]).toEqual({ lexicon: "aws", status: "unresolved", reason: "no-credentials" });
+    expect(identityStatusText(rows[0])).toContain("no identity is configured");
+    expect(rows[1]).toEqual({
+      lexicon: "k8s",
+      status: "unresolved",
+      reason: "read-failed",
+      detail: "connection refused",
+    });
+    expect(identityStatusText(rows[1])).toContain("self-query failed");
+    // The point of the distinction: "nothing is configured" and "I could not
+    // find out" must never render as the same row.
+    expect(identityStatusText(rows[0])).not.toBe(identityStatusText(rows[1]));
+  });
+
+  test("an empty principal is refused rather than reported as an identity", () => {
+    const row = identityRowFor("gcp", { identity: "   ", scope: "acme-prod", source: "ADC" }, {});
+    expect(row.status).toBe("unresolved");
+    expect(row.reason).toBe("read-failed");
+    expect(row.identity).toBeUndefined();
+  });
+
+  test("a lexicon that throws degrades to read-failed and never fails the run", async () => {
+    const rows = await describeIdentities(
+      [
+        {
+          name: "azure",
+          describeIdentity: async () => {
+            throw new Error("az CLI is not installed");
+          },
+        },
+        { name: "aws", describeIdentity: async () => ({ identity: "arn:x", scope: "s", source: "env" }) },
+      ],
+      { environment: "prod" },
+      {},
+    );
+    expect(rows[0]).toEqual({
+      lexicon: "azure",
+      status: "unresolved",
+      reason: "read-failed",
+      detail: "az CLI is not installed",
+    });
+    expect(rows[1].status).toBe("reported");
+  });
+
+  test("rows come back in the order the lexicons were configured", async () => {
+    const names = ["k8s", "aws", "gcp", "github"];
+    const rows = await describeIdentities(
+      names.map((name) => ({ name })),
+      { environment: "prod" },
+      {},
+    );
+    expect(rows.map((r) => r.lexicon)).toEqual(names);
+  });
+
+  test("the environment, region and cwd reach the lexicon unchanged", async () => {
+    const seen: unknown[] = [];
+    await describeIdentities(
+      [
+        {
+          name: "aws",
+          describeIdentity: async (options) => {
+            seen.push(options);
+            return { identity: "arn:x", scope: "s", source: "env" };
+          },
+        },
+      ],
+      { environment: "prod", region: "eu-west-1", cwd: "/repo" },
+      {},
+    );
+    expect(seen).toEqual([{ environment: "prod", region: "eu-west-1", cwd: "/repo" }]);
+  });
+
+  test("isUnresolvedIdentity discriminates the two return shapes", () => {
+    expect(isUnresolvedIdentity({ unresolved: { reason: "no-binding" } })).toBe(true);
+    expect(isUnresolvedIdentity({ identity: "a", scope: "b", source: "c" })).toBe(false);
+  });
+});
+
+describe("no credential reaches the output (#1982)", () => {
+  test("a value held in a credential-named env var is redacted wherever it appears", () => {
+    const env = { GITHUB_TOKEN: "ghp_averyrealtokenvalue", HOME: "/Users/x" };
+    expect(redactCredentialMaterial("authorized by ghp_averyrealtokenvalue", env)).toBe(
+      `authorized by ${REDACTED}`,
+    );
+  });
+
+  test("every free-text field of a row is scrubbed, not just the identity", () => {
+    const env = { AWS_SECRET_ACCESS_KEY: "wJalrXUtnFEMIsecretKEY" };
+    const row = redactIdentityRow(
+      {
+        lexicon: "aws",
+        status: "reported",
+        identity: "wJalrXUtnFEMIsecretKEY",
+        scope: "wJalrXUtnFEMIsecretKEY",
+        source: "signed with wJalrXUtnFEMIsecretKEY",
+        endpoint: "https://sts.amazonaws.com/?k=wJalrXUtnFEMIsecretKEY",
+        detail: "wJalrXUtnFEMIsecretKEY",
+      },
+      env,
+    );
+    for (const field of [row.identity, row.scope, row.source, row.endpoint, row.detail]) {
+      expect(field).not.toContain("wJalrXUtnFEMIsecretKEY");
+      expect(field).toContain(REDACTED);
+    }
+  });
+
+  test("a short env value is not treated as a credential", () => {
+    // Redacting "dev" out of every identity would be worse than the leak.
+    expect(redactCredentialMaterial("cluster dev-a", { AUTH_TOKEN: "dev" })).toBe("cluster dev-a");
+  });
+
+  test("literal credential shapes are redacted with no env var involved", () => {
+    const jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.dBjftJeZ4CVPmB92K27u";
+    expect(redactCredentialMaterial(jwt, {})).toBe(REDACTED);
+    expect(redactCredentialMaterial("Bearer abcdefghijklmnopqrstuvwxyz012345", {})).toBe(REDACTED);
+    expect(
+      redactCredentialMaterial("-----BEGIN RSA PRIVATE KEY-----\nAAAA\n-----END RSA PRIVATE KEY-----", {}),
+    ).toBe(REDACTED);
+  });
+
+  test("real principals survive redaction unchanged", () => {
+    // A mangled principal is a wrong answer, not a safe one. Nothing here is
+    // entropy-scored, so these pass through whole.
+    const env = { AWS_SESSION_TOKEN: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN" };
+    for (const principal of [
+      "arn:aws:sts::491500000000:assumed-role/deploy/ci",
+      "system:serviceaccount:chant:deployer",
+      "deploy@acme.iam.gserviceaccount.com",
+      "https://prod-eks-a.eu-west-1.eks.amazonaws.com",
+      "491500000000 us-east-1",
+    ]) {
+      expect(redactCredentialMaterial(principal, env)).toBe(principal);
+    }
+  });
+
+  test("an identity built out of the session token is redacted, not printed", () => {
+    const env = { AWS_SESSION_TOKEN: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN" };
+    const row = identityRowFor(
+      "aws",
+      { identity: "FwoGZXIvYXdzEBYaDLONGSESSIONTOKEN", scope: "us-east-1", source: "env" },
+      env,
+    );
+    expect(row.identity).toBe(REDACTED);
+    expect(row.identity).not.toContain("FwoGZXIvYXdz");
+  });
+});