@intentius/chant-lexicon-cpln 0.53.0

package/src/lint/rules/cpl001-no-secret-literals.ts

@@ -0,0 +1,83 @@
+import ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * CPL001: no literal credential material in a cpln declaration.
+ *
+ * This is a source-level rule rather than a post-synth check on purpose. By
+ * the time the manifest exists, a literal is just a string in a `data` block
+ * and there is nothing left to point at; here there is a file and a line, which
+ * is what makes the finding actionable — and, more to the point, this is the
+ * form the credential is in when it enters git history.
+ *
+ * `Secret` is the obvious carrier, but a credential pasted into a workload's
+ * env or an identity's cloud config is the same leak, so the rule fires
+ * anywhere inside a `new <cpln kind>(…)`.
+ *
+ * Complementary to CPL012, which catches the shape this cannot see — a
+ * plausible-looking value in a credential-named env var — from the model.
+ */
+
+const CPLN_KINDS = new Set(["Gvc", "Workload", "Identity", "VolumeSet", "Secret", "Policy", "Domain", "IpSet"]);
+
+const CREDENTIAL_SHAPES: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /^-----BEGIN [A-Z ]*PRIVATE KEY-----/, label: "private key material" },
+  { pattern: /^AKIA[0-9A-Z]{16}$/, label: "AWS access key id" },
+  { pattern: /^(ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}$/, label: "GitHub token" },
+  { pattern: /^github_pat_[A-Za-z0-9_]{20,}$/, label: "GitHub fine-grained token" },
+  { pattern: /^sk-[A-Za-z0-9_-]{20,}$/, label: "secret API key (sk-)" },
+  { pattern: /^xox[baprs]-[A-Za-z0-9-]{10,}$/, label: "Slack token" },
+  { pattern: /^ya29\.[A-Za-z0-9_-]{20,}$/, label: "Google OAuth access token" },
+  { pattern: /^eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}$/, label: "JWT" },
+  {
+    pattern: /^postgres(ql)?:\/\/[^:@/\s]+:[^@/\s]+@/,
+    label: "database URL with an inline password",
+  },
+  { pattern: /^mysql:\/\/[^:@/\s]+:[^@/\s]+@/, label: "database URL with an inline password" },
+  { pattern: /^mongodb(\+srv)?:\/\/[^:@/\s]+:[^@/\s]+@/, label: "database URL with an inline password" },
+];
+
+export const noSecretLiteralsRule: LintRule = {
+  id: "CPL001",
+  severity: "error",
+  category: "security",
+  description: "No literal credential material in cpln declarations — reference a secret instead",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const visit = (node: ts.Node, insideCplnNew: boolean): void => {
+      let inside = insideCplnNew;
+
+      if (ts.isNewExpression(node)) {
+        const name = node.expression.getText(source);
+        const short = name.split(".").pop() ?? name;
+        if (CPLN_KINDS.has(short)) inside = true;
+      }
+
+      if (inside && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))) {
+        for (const { pattern, label } of CREDENTIAL_SHAPES) {
+          if (!pattern.test(node.text)) continue;
+          const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+          diagnostics.push({
+            ruleId: "CPL001",
+            severity: "error",
+            message:
+              `Literal ${label} in a cpln declaration. Store it as a Secret and reference it as ` +
+              `\`cpln://secret/NAME.FIELD\` — a literal here is a credential in git history.`,
+            file: context.filePath,
+            line: line + 1,
+            column: character + 1,
+          });
+          break;
+        }
+      }
+
+      ts.forEachChild(node, (child) => visit(child, inside));
+    };
+
+    visit(source, false);
+    return diagnostics;
+  },
+};

package/src/lint/rules/cpl002-prefer-resource-reference.ts

@@ -0,0 +1,71 @@
+import ts from "typescript";
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * CPL002: prefer a resource reference over a hand-written link.
+ *
+ * The cpln serializer resolves a declared resource passed where a link is
+ * expected into the correct link for its kind — including the GVC qualifier
+ * that the identity form needs and that is silently ignored when missing. A
+ * hand-spelled `"//gvc/prod/identity/api"` gets none of that: it does not
+ * follow a rename, it is not checked against anything at author time, and
+ * getting the shape subtly wrong fails at runtime rather than at apply.
+ *
+ * This is a style rule, not a correctness one — the literal form is valid, and
+ * is the only option for a resource this stack does not declare. It fires on
+ * the link syntax specifically, so ordinary strings are untouched.
+ *
+ * Not flagged: `cpln://secret/…` and `cpln://volumeset/…`. Those are runtime
+ * *resolution* URIs read by the container, not links between resources, and
+ * they have no reference form to prefer.
+ */
+
+const CPLN_KINDS = new Set(["Gvc", "Workload", "Identity", "VolumeSet", "Secret", "Policy", "Domain", "IpSet"]);
+
+/** `//gvc/prod/identity/api` or `//secret/db-password`. */
+const LINK = /^\/\/(?:gvc\/[^/\s]+\/)?(gvc|workload|identity|volumeset|secret|policy|domain|ipset)\/[^/\s]+$/;
+
+export const preferResourceReferenceRule: LintRule = {
+  id: "CPL002",
+  severity: "info",
+  category: "style",
+  description: "Prefer passing a declared resource over a hand-written Control Plane link",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const source = context.sourceFile;
+
+    const visit = (node: ts.Node, insideCplnNew: boolean): void => {
+      let inside = insideCplnNew;
+
+      if (ts.isNewExpression(node)) {
+        const name = node.expression.getText(source);
+        const short = name.split(".").pop() ?? name;
+        if (CPLN_KINDS.has(short)) inside = true;
+      }
+
+      if (inside && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))) {
+        const match = LINK.exec(node.text);
+        if (match) {
+          const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+          diagnostics.push({
+            ruleId: "CPL002",
+            severity: "info",
+            message:
+              `Hand-written link "${node.text}". If the ${match[1]} is declared in this stack, pass the ` +
+              `resource itself — the serializer emits the correct link, including the GVC qualifier, and ` +
+              `the reference follows a rename.`,
+            file: context.filePath,
+            line: line + 1,
+            column: character + 1,
+          });
+        }
+      }
+
+      ts.forEachChild(node, (child) => visit(child, inside));
+    };
+
+    visit(source, false);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,9 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { noSecretLiteralsRule } from "./cpl001-no-secret-literals";
+import { preferResourceReferenceRule } from "./cpl002-prefer-resource-reference";
+
+export { noSecretLiteralsRule } from "./cpl001-no-secret-literals";
+export { preferResourceReferenceRule } from "./cpl002-prefer-resource-reference";
+
+/** All source-level lint rules provided by this lexicon (imported by plugin.ts). */
+export const rules: LintRule[] = [noSecretLiteralsRule, preferResourceReferenceRule];

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { rules, noSecretLiteralsRule, preferResourceReferenceRule } from "./index";
+
+function lint(rule: (typeof rules)[number], source: string) {
+  const sourceFile = ts.createSourceFile("infra.ts", source, ts.ScriptTarget.Latest, true);
+  return rule.check({ sourceFile, entities: [], filePath: "infra.ts", lexicon: "cpln" } as LintContext);
+}
+
+describe("cpln lint rules", () => {
+  it("registers rules with unique ids under the CPL prefix", () => {
+    expect(rules.length).toBeGreaterThan(0);
+    const ids = rules.map((rule) => rule.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    for (const id of ids) expect(id.startsWith("CPL")).toBe(true);
+  });
+});
+
+describe("CPL001 no secret literals", () => {
+  it("flags a private key in a Secret", () => {
+    const found = lint(
+      noSecretLiteralsRule,
+      `const s = new Secret({ name: "tls", type: "tls", data: { key: "-----BEGIN RSA PRIVATE KEY-----abc" } });`,
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0].ruleId).toBe("CPL001");
+    expect(found[0].severity).toBe("error");
+    expect(found[0].line).toBe(1);
+  });
+
+  it("flags a database URL with an inline password in a Workload", () => {
+    const found = lint(
+      noSecretLiteralsRule,
+      `const w = new Workload({ name: "api", gvc: "prod", spec: { containers: [{ env: [{ name: "URL", value: "postgres://u:p@host/db" }] }] } });`,
+    );
+    expect(found).toHaveLength(1);
+  });
+
+  it("flags an AWS access key id", () => {
+    expect(
+      lint(noSecretLiteralsRule, `const s = new Secret({ name: "k", data: { accessKey: "AKIAIOSFODNN7EXAMPLE" } });`),
+    ).toHaveLength(1);
+  });
+
+  it("ignores credential shapes outside a cpln declaration", () => {
+    // The rule is scoped to cpln constructors on purpose — a fixture in a test
+    // file or an unrelated const is not this rule's business.
+    expect(lint(noSecretLiteralsRule, `const fixture = "AKIAIOSFODNN7EXAMPLE";`)).toEqual([]);
+  });
+
+  it("accepts a secret reference", () => {
+    expect(
+      lint(
+        noSecretLiteralsRule,
+        `const w = new Workload({ spec: { containers: [{ env: [{ value: "cpln://secret/db.payload" }] }] } });`,
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe("CPL002 prefer a resource reference", () => {
+  it("flags a hand-written GVC-qualified link", () => {
+    const found = lint(
+      preferResourceReferenceRule,
+      `const w = new Workload({ name: "api", spec: { identityLink: "//gvc/prod/identity/api" } });`,
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0].severity).toBe("info");
+  });
+
+  it("flags a hand-written org-scoped link", () => {
+    expect(
+      lint(preferResourceReferenceRule, `const p = new Policy({ targetLinks: ["//secret/db-password"] });`),
+    ).toHaveLength(1);
+  });
+
+  it("leaves runtime resolution URIs alone", () => {
+    // `cpln://secret/…` is read by the container at runtime, not a reference
+    // between resources, so there is no reference form to prefer.
+    expect(
+      lint(
+        preferResourceReferenceRule,
+        `const w = new Workload({ spec: { containers: [{ env: [{ value: "cpln://secret/db.payload" }] }] } });`,
+      ),
+    ).toEqual([]);
+    expect(
+      lint(preferResourceReferenceRule, `const w = new Workload({ spec: { containers: [{ volumes: [{ uri: "cpln://volumeset/data" }] }] } });`),
+    ).toEqual([]);
+  });
+
+  it("leaves location links alone", () => {
+    // `/org/…/location/…` names a platform-provided resource this lexicon does
+    // not model, so there is nothing to pass instead.
+    expect(
+      lint(
+        preferResourceReferenceRule,
+        `const g = new Gvc({ spec: { staticPlacement: { locationLinks: ["/org/acme/location/aws-us-east-1"] } } });`,
+      ),
+    ).toEqual([]);
+  });
+
+  it("ignores ordinary strings", () => {
+    expect(lint(preferResourceReferenceRule, `const w = new Workload({ name: "api", description: "the api" });`)).toEqual(
+      [],
+    );
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+import { completions } from "./completions";
+
+function ctx(content: string, linePrefix = content.split("\n").pop() ?? ""): CompletionContext {
+  const lines = content.split("\n");
+  return {
+    uri: "file:///infra.ts",
+    content,
+    position: { line: lines.length - 1, character: lines[lines.length - 1].length },
+    wordAtCursor: "",
+    linePrefix,
+  };
+}
+
+describe("cpln LSP completions", () => {
+  it("returns an array", () => {
+    expect(Array.isArray(completions(ctx("")))).toBe(true);
+  });
+
+  it("offers the resource classes after `new `", () => {
+    const labels = completions(ctx("const w = new ")).map((item) => item.label);
+    for (const kind of ["Gvc", "Workload", "Identity", "VolumeSet", "Secret", "Policy", "Domain", "IpSet"]) {
+      expect(labels, `${kind} missing from completions`).toContain(kind);
+    }
+  });
+
+  it("offers a workload's property names inside its constructor", () => {
+    const labels = completions(ctx("const w = new Workload({\n  ", "  ")).map((item) => item.label);
+    expect(labels).toContain("name");
+    expect(labels).toContain("spec");
+    // The property GVC-scoped kinds carry, which the OpenAPI document does not.
+    expect(labels).toContain("gvc");
+  });
+
+  it("does not offer read-only attributes as properties", () => {
+    // These are attributes, not authoring surface — and Control Plane rejects a
+    // manifest carrying them, which is why they must not be suggested.
+    const labels = completions(ctx("const w = new Workload({\n  ", "  ")).map((item) => item.label);
+    for (const attribute of ["id", "status", "created", "lastModified", "links"]) {
+      expect(labels, `${attribute} is an attribute, not authoring surface`).not.toContain(attribute);
+    }
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,27 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+/**
+ * The generated registry, loaded once. It carries every cpln resource and
+ * property type with its constraints, which is exactly what the shared
+ * completion provider indexes — so completions cannot drift from the types.
+ */
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-cpln.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * LSP completions for cpln resources — class names after `new `, property
+ * names inside a constructor.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "cpln resource");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import type { HoverContext } from "@intentius/chant/lsp/types";
+import { hover } from "./hover";
+
+function ctx(word: string): HoverContext {
+  const lineText = `const x = new ${word}({});`;
+  return {
+    uri: "file:///infra.ts",
+    content: lineText,
+    position: { line: 0, character: lineText.indexOf(word) + 1 },
+    word,
+    lineText,
+  };
+}
+
+describe("cpln LSP hover", () => {
+  it("returns nothing for an unknown identifier", () => {
+    expect(hover(ctx("NotACplnThing"))).toBeUndefined();
+  });
+
+  it("names the Control Plane type and manifest kind for a resource", () => {
+    const info = hover(ctx("Workload"));
+    expect(info?.contents).toContain("Cpln::Core::Workload");
+    expect(info?.contents).toContain("kind: `workload`".replace("kind: ", "Manifest kind: "));
+  });
+
+  it("says a GVC-scoped kind needs a gvc", () => {
+    expect(hover(ctx("Workload"))?.contents).toContain("GVC-scoped");
+    expect(hover(ctx("VolumeSet"))?.contents).toContain("GVC-scoped");
+    expect(hover(ctx("Gvc"))?.contents).not.toContain("GVC-scoped —");
+  });
+
+  it("carries the silent-failure notes the types cannot express", () => {
+    // These are the reason hover exists here: the property list is already in
+    // the types; what an author cannot see is which mistakes fail quietly.
+    expect(hover(ctx("Identity"))?.contents).toContain("silently ignored");
+    expect(hover(ctx("Secret"))?.contents).toContain("fails silently");
+    expect(hover(ctx("VolumeSet"))?.contents).toContain("immutable");
+    expect(hover(ctx("Workload"))?.contents).toContain("immutable");
+  });
+
+  it("spells out enumerated properties", () => {
+    const info = hover(ctx("Secret"));
+    expect(info?.contents).toContain("Enumerated properties:");
+    expect(info?.contents).toContain("`opaque`");
+  });
+
+  it("marks a property type as nested and names its owner", () => {
+    const info = hover(ctx("WorkloadSpecContainers"));
+    expect(info?.contents).toContain("Property type");
+    expect(info?.contents).toContain("Workload");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,130 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { KINDS, kindByClassName } from "../kinds";
+
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-cpln.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Per-kind notes.
+ *
+ * These carry the rules an author cannot infer from the property names, and
+ * specifically the ones whose violation fails *silently* — an unqualified
+ * identity link, a scale-to-zero that never happens, an immutable field. The
+ * property list is already in the types; what hover adds is the part the types
+ * cannot say.
+ */
+const KIND_NOTES: Record<string, string> = {
+  Gvc:
+    "The placement and networking boundary. Workloads, identities and volume sets live inside one.\n\n" +
+    "Placement is set here, not per workload (`spec.staticPlacement.locationLinks`, e.g. " +
+    "`/org/acme/location/aws-us-east-1`). **Pull secrets are also GVC-level** (`spec.pullSecretLinks`) — " +
+    "only `docker`, `ecr` and `gcp` secret types are valid. KEDA must be enabled here before a standard or " +
+    "stateful workload in the GVC can use it.",
+
+  Workload:
+    "A running unit of work. **`type` and `name` are immutable** — changing either means delete and recreate.\n\n" +
+    "- `serverless` — exactly one HTTP port, required. Scales to zero with `rps` or `concurrency`.\n" +
+    "- `standard` — multiple ports, non-HTTP allowed. Scale to zero via KEDA only.\n" +
+    "- `stateful` — stable replica identity; the only type that mounts `ext4`/`xfs` volumes or uses " +
+    "`replicaDirect` load balancing.\n" +
+    "- `cron` — must set `spec.job.schedule` and expose no ports. Probes, autoscaling and `timeoutSeconds` " +
+    "are accepted and ignored.\n\n" +
+    "Capacity AI is **on by default** for serverless, standard and cron, and conflicts with CPU-utilization " +
+    "autoscaling, multi-metric autoscaling, and GPUs. Memory(MiB)/CPU(millicores) must be ≤ 8.",
+
+  Identity:
+    "A workload's identity: cloud-provider access, network resources, and the principal a policy grants to.\n\n" +
+    "**GVC-scoped and not shareable** — an identity cannot be used from another GVC; declare one per GVC with " +
+    "the same spec. A workload has at most one. Each provider section allows one account " +
+    "(AWS `roleName` ⊻ `policyRefs`, GCP `serviceAccount` ⊻ `bindings`).\n\n" +
+    "In a policy binding the principal must be `//gvc/GVC/identity/NAME`. The bare `//identity/NAME` is " +
+    "**silently ignored** (CPL013).",
+
+  VolumeSet:
+    "Persistent storage inside one GVC.\n\n" +
+    "**`fileSystemType` and `performanceClass` are both immutable** — changing either means delete, recreate, " +
+    "and data loss. `ext4`/`xfs` are RWO and bind to exactly one *stateful* workload; `shared` is RWX, works " +
+    "with any type, and supports no snapshots. `high-throughput-ssd` has a 200 GB floor where the others have " +
+    "10 GB. Mount with `cpln://volumeset/NAME`.",
+
+  Secret:
+    "An org-scoped secret, in one of 12 types.\n\n" +
+    "Reading one at runtime takes three steps, and **missing any one fails silently**: the workload has an " +
+    "identity, a policy grants that identity `reveal` on the secret, and the reference is field-qualified — " +
+    "`cpln://secret/NAME.payload`, not `cpln://secret/NAME` (CPL014).",
+
+  Policy:
+    "Binds permissions to principals over a target.\n\n" +
+    "`targetKind` is singular and lowercase. Pick exactly one scope: `target: \"all\"`, `targetLinks`, or " +
+    "`targetQuery`. `ipset` and `mk8s` are **not** valid targets — they are governed through their parent. " +
+    "Permissions in a binding must be sorted and unique. Never set `origin` by hand.",
+
+  Domain:
+    "A custom domain with its TLS, CORS and routing.\n\n" +
+    "**Apex domains must use `dnsMode: cname`** — NS does not support apex. NS mode requires " +
+    "`certChallengeType: dns01`. `gvcLink`, `workloadLink` and `ports[].routes` are mutually exclusive, and " +
+    "`workloadLink` (replica-direct) is stateful-only. Every route must target workloads in one GVC.",
+
+  IpSet:
+    "Dedicated IP addresses reserved in named locations and bound to a workload.\n\n" +
+    "Not a valid policy target — access is governed through the workload it fronts.",
+};
+
+/** Enum-valued props are worth spelling out inline — they are the typo surface. */
+function enumLines(entry: LexiconEntry): string[] {
+  const constraints = entry.propertyConstraints as Record<string, { enum?: unknown[] }> | undefined;
+  if (!constraints) return [];
+
+  const lines: string[] = [];
+  for (const [prop, constraint] of Object.entries(constraints)) {
+    if (!Array.isArray(constraint?.enum) || constraint.enum.length === 0) continue;
+    lines.push(`- \`${prop}\`: ${constraint.enum.map((v) => `\`${String(v)}\``).join(" | ")}`);
+  }
+  return lines;
+}
+
+function cplnHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [`**${className}**`, "", `Control Plane type: \`${entry.resourceType}\``];
+
+  const kind = kindByClassName(className);
+  if (!kind) {
+    // A property type — a nested shape rather than a standalone declarable.
+    // Naming its owner is the useful part, since the names are path-derived.
+    const owner = KINDS.find((k) => className.startsWith(k.className));
+    lines.push(
+      "",
+      owner
+        ? `*Property type — a nested shape within \`${owner.className}\`, not a standalone declarable.*`
+        : "*Property type — a nested shape, not a standalone declarable.*",
+    );
+    const propertyEnums = enumLines(entry);
+    if (propertyEnums.length > 0) lines.push("", "Enumerated properties:", ...propertyEnums);
+    return { contents: lines.join("\n") };
+  }
+
+  lines.push("", `Manifest kind: \`${kind.kind}\``);
+  if (kind.gvcScoped) lines.push("", "GVC-scoped — requires a `gvc`.");
+
+  const note = KIND_NOTES[className];
+  if (note) lines.push("", note);
+
+  const enums = enumLines(entry);
+  if (enums.length > 0) lines.push("", "Enumerated properties:", ...enums);
+
+  return { contents: lines.join("\n") };
+}
+
+/** Provide LSP hover information for cpln resources. */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), cplnHover);
+}

package/src/ownership.ts

@@ -0,0 +1,28 @@
+/**
+ * The cpln lexicon's ownership convention.
+ *
+ * Declared here rather than in core — the same seam aws (`chant:managed-by`),
+ * azure and fly sit on. Core owns the generic stamp/detect logic; each lexicon
+ * owns key names its provider will actually accept.
+ *
+ * Control Plane gives every kind a free-form `tags` map, which makes this the
+ * cleanest ownership channel of any target chant supports: one uniform place on
+ * all eight kinds, readable straight off a plain `GET`, with no per-kind
+ * special case of the sort fly needs for volumes and certificates.
+ *
+ * Key naming. Tag keys accept a `/`, which Control Plane uses itself for its
+ * reserved `cpln/…` keys (`cpln/relaxMemoryToCpuRatio`). A prefixed key is
+ * therefore both idiomatic and safely namespaced against a future reserved key,
+ * so these follow the same `chant.intentius.io/…` convention as the shared
+ * label channel rather than inventing a flat spelling. The `cpln/` prefix is
+ * Control Plane's own and is never written here.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/** Tag keys carrying chant's ownership marker on every cpln resource. */
+export const CPLN_TAG_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "chant.intentius.io/managed-by",
+  stack: "chant.intentius.io/stack",
+  env: "chant.intentius.io/env",
+};

package/src/package-cli.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env tsx
+/**
+ * Entry point for `npm run bundle` — generates `src/generated/` and writes the
+ * `dist/` bundle.
+ *
+ * Top-level await rather than an async wrapper, matching the other lexicons:
+ * an async main() leaves event-loop references that keep the process alive
+ * after the bundle is written.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { packageLexicon } from "./codegen/package";
+
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+const force = process.argv.includes("--force");
+
+const { spec, stats } = await packageLexicon({ verbose, force });
+writeBundleSpec(spec, distDir);
+
+console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);