@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/import-source.ts

@@ -0,0 +1,462 @@
+/**
+ * `chant workspace init --from tfc|spacelift|backstage` (#3178): propose a
+ * declaration from structure that lives outside the repository.
+ *
+ * Each source is read into a small input document (see the `*Input` types),
+ * and the mapping from that document to a proposal is a pure function. The
+ * Terraform Cloud and Spacelift documents come from their APIs
+ * (`import-fetch.ts`) or from an exported file given with `--input`; tests
+ * feed fixture JSON and never open a connection. Backstage is read from
+ * `catalog-info.yaml` files on disk.
+ *
+ * What maps:
+ *
+ * - a TFC workspace or a Spacelift stack becomes a member (`terraform` for a
+ *   Terraform stack, `other` with a `because` for anything else);
+ * - a TFC run trigger, or a Spacelift stack dependency, becomes a link on the
+ *   consumer to an output of the producer;
+ * - an environment is read from the `env:` or `environment:` tag or label, or
+ *   the Backstage `spec.lifecycle`;
+ * - policy sets and policies become constraint records;
+ * - a Backstage component or resource becomes an `other` member, and its
+ *   `dependsOn` becomes links.
+ *
+ * Everything else is listed in `leftOut`, with the reason, so the user sees
+ * what the import did not carry.
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import yaml from "js-yaml";
+import { NAME_PATTERN, parseDeclaration } from "./declaration";
+import { sanitizeName } from "./init";
+
+export const IMPORT_SOURCES = ["tfc", "spacelift", "backstage"] as const;
+export type ImportSource = (typeof IMPORT_SOURCES)[number];
+
+/** The output every imported producer exposes when its source names none: "this member was applied". */
+export const APPLIED_OUTPUT = "applied";
+/** The output a Backstage entity exposes to the entities that depend on it. */
+export const CATALOG_OUTPUT = "catalog";
+
+// ── Inputs ───────────────────────────────────────────────────────────────────
+
+export interface TfcInput {
+  organization: string;
+  projects?: { id: string; name: string }[];
+  workspaces: {
+    id: string;
+    name: string;
+    project?: string;
+    workingDirectory?: string;
+    terraformVersion?: string;
+    vcsRepo?: string;
+    tags?: string[];
+    variables?: { key: string; category?: string; sensitive?: boolean }[];
+    /** Workspace ids (or names) whose runs trigger this one. */
+    runTriggers?: string[];
+    notifications?: number;
+  }[];
+  policySets?: { id?: string; name: string; kind?: string; enforcement?: string; workspaces?: string[]; global?: boolean }[];
+}
+
+export interface SpaceliftInput {
+  account: string;
+  stacks: {
+    id: string;
+    name: string;
+    space?: string;
+    repository?: string;
+    branch?: string;
+    projectRoot?: string;
+    vendor?: string;
+    labels?: string[];
+    dependsOn?: { stack: string; references?: { outputName: string; inputName?: string }[] }[];
+    policies?: string[];
+    contexts?: string[];
+  }[];
+  policies?: { id: string; name: string; type?: string }[];
+}
+
+// ── Result ───────────────────────────────────────────────────────────────────
+
+export interface ImportedMember {
+  name: string;
+  dir: string;
+  kind: string;
+  because?: string;
+  outputs?: string[];
+  links?: { member: string; output: string }[];
+}
+
+export interface ConstraintRecord {
+  id: string;
+  kind: "constraint";
+  source: ImportSource;
+  title: string;
+  policyKind?: string;
+  enforcement?: string;
+  /** The members the constraint applies to; empty means all of them. */
+  appliesTo: string[];
+}
+
+export interface EnvironmentRecord {
+  name: string;
+  members: string[];
+}
+
+export interface LeftOut {
+  what: string;
+  count: number;
+  why: string;
+}
+
+export interface ImportProposal {
+  source: ImportSource;
+  declaration: { name: string; schema: 1; members: ImportedMember[] };
+  environments: EnvironmentRecord[];
+  records: ConstraintRecord[];
+  leftOut: LeftOut[];
+  /** Plain-language notes the user should read before writing, such as the kind pin the proposal needs. */
+  notes: string[];
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function nameFor(raw: string, taken: Set<string>): string {
+  let base = sanitizeName(raw) || "member";
+  if (!NAME_PATTERN.test(base)) base = "member";
+  let name = base;
+  for (let i = 2; taken.has(name); i++) name = `${base.slice(0, 36)}-${i}`;
+  taken.add(name);
+  return name;
+}
+
+function cleanDir(raw: string | undefined, fallback: string): string {
+  const d = (raw ?? "").trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+  if (d === "" || d === "." || d.startsWith("/") || d.split("/").includes("..")) return fallback;
+  return d;
+}
+
+const ENV_TAG = /^(?:env|environment)[:=](.+)$/i;
+function envOf(tags: string[] | undefined): string[] {
+  return (tags ?? []).map((t) => ENV_TAG.exec(t)?.[1]?.trim()).filter((e): e is string => !!e);
+}
+
+function addEnv(map: Map<string, string[]>, env: string, member: string): void {
+  const list = map.get(env) ?? [];
+  if (!list.includes(member)) list.push(member);
+  map.set(env, list);
+}
+
+function envList(map: Map<string, string[]>): EnvironmentRecord[] {
+  return [...map].map(([name, members]) => ({ name, members })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function addLink(member: ImportedMember, producer: ImportedMember, output: string): void {
+  producer.outputs = [...new Set([...(producer.outputs ?? []), output])];
+  member.links = [...(member.links ?? [])];
+  if (!member.links.some((l) => l.member === producer.name && l.output === output)) member.links.push({ member: producer.name, output });
+}
+
+function finish(source: ImportSource, workspaceName: string, members: ImportedMember[], parts: Omit<ImportProposal, "source" | "declaration">): ImportProposal {
+  const declaration = { name: nameFor(workspaceName, new Set()), schema: 1 as const, members };
+  // The same check `init` makes: it must read back as a valid declaration.
+  parseDeclaration(JSON.stringify(declaration), "chant.workspace.json");
+  return { source, declaration, ...parts };
+}
+
+const TF_NOTE =
+  "Members of kind terraform get their kind from @intentius/chant-lexicon-terraform: pin that package in the declaration's pins before chant workspace check will read them.";
+
+// ── Terraform Cloud ──────────────────────────────────────────────────────────
+
+export function proposeFromTfc(input: TfcInput, options: { name?: string } = {}): ImportProposal {
+  const taken = new Set<string>();
+  const byRef = new Map<string, ImportedMember>();
+  const members: ImportedMember[] = [];
+  const projects = new Map((input.projects ?? []).map((p) => [p.id, p.name]));
+  const envs = new Map<string, string[]>();
+  let variables = 0;
+  let sensitive = 0;
+  let vcs = 0;
+  let notifications = 0;
+
+  const byDir = new Map<string, ImportedMember>();
+  let shared = 0;
+  for (const w of input.workspaces) {
+    const dirKey = cleanDir(w.workingDirectory, `\0${w.name}`);
+    const first = byDir.get(dirKey);
+    if (first) {
+      // One member per directory: a workspace on the same configuration folds into the first.
+      byRef.set(w.id, first);
+      byRef.set(w.name, first);
+      for (const e of envOf(w.tags)) addEnv(envs, e, first.name);
+      shared++;
+      continue;
+    }
+    const name = nameFor(w.name, taken);
+    const project = w.project ? projects.get(w.project) : undefined;
+    const m: ImportedMember = {
+      name,
+      dir: dirKey.startsWith("\0") ? name : dirKey,
+      kind: "terraform",
+      because: `Terraform Cloud workspace ${input.organization}/${w.name}${project ? ` in project ${project}` : ""}`,
+    };
+    members.push(m);
+    byDir.set(dirKey, m);
+    byRef.set(w.id, m);
+    byRef.set(w.name, m);
+    for (const e of envOf(w.tags)) addEnv(envs, e, name);
+    variables += w.variables?.length ?? 0;
+    sensitive += (w.variables ?? []).filter((v) => v.sensitive).length;
+    if (w.vcsRepo) vcs++;
+    notifications += w.notifications ?? 0;
+  }
+
+  let triggers = 0;
+  let dangling = 0;
+  for (const w of input.workspaces) {
+    const consumer = byRef.get(w.id)!;
+    for (const src of w.runTriggers ?? []) {
+      const producer = byRef.get(src);
+      if (!producer || producer === consumer) {
+        dangling++;
+        continue;
+      }
+      addLink(consumer, producer, APPLIED_OUTPUT);
+      triggers++;
+    }
+  }
+
+  const records: ConstraintRecord[] = (input.policySets ?? []).map((p, i) => ({
+    id: `tfc-policy-${sanitizeName(p.name) || i}`,
+    kind: "constraint",
+    source: "tfc",
+    title: p.name,
+    ...(p.kind ? { policyKind: p.kind } : {}),
+    ...(p.enforcement ? { enforcement: p.enforcement } : {}),
+    appliesTo: p.global ? [] : (p.workspaces ?? []).map((r) => byRef.get(r)?.name).filter((n): n is string => !!n),
+  }));
+
+  const leftOut: LeftOut[] = [];
+  if (variables > 0) leftOut.push({ what: "variables", count: variables, why: `${sensitive} are sensitive and their values are never read; the keys stay in Terraform Cloud` });
+  if (vcs > 0) leftOut.push({ what: "VCS connections", count: vcs, why: "the repository link belongs to the CI that replaces Terraform Cloud's runs" });
+  if (notifications > 0) leftOut.push({ what: "notification configurations", count: notifications, why: "a workspace has no notification record" });
+  if (shared > 0) leftOut.push({ what: "workspaces sharing a directory", count: shared, why: "a member is one directory; each folds into the first workspace on it, with its environments and run triggers" });
+  if (dangling > 0) leftOut.push({ what: "run triggers", count: dangling, why: "their source workspace is not in the input, or is the workspace itself" });
+  if ((input.projects ?? []).length > 0) leftOut.push({ what: "projects", count: input.projects!.length, why: "named in each member's because; a project is not a declared grouping" });
+  leftOut.push({ what: "state and run history", count: input.workspaces.length, why: "state is adopted when a member is promoted, not copied by init" });
+  void triggers;
+
+  return finish("tfc", options.name ?? input.organization, members, { environments: envList(envs), records, leftOut, notes: [TF_NOTE] });
+}
+
+// ── Spacelift ────────────────────────────────────────────────────────────────
+
+export function proposeFromSpacelift(input: SpaceliftInput, options: { name?: string } = {}): ImportProposal {
+  const taken = new Set<string>();
+  const byRef = new Map<string, ImportedMember>();
+  const members: ImportedMember[] = [];
+  const envs = new Map<string, string[]>();
+  let nonTerraform = 0;
+  let contexts = 0;
+
+  const byDir = new Map<string, ImportedMember>();
+  let shared = 0;
+  for (const s of input.stacks) {
+    const dirKey = cleanDir(s.projectRoot, `\0${s.name}`);
+    const first = byDir.get(dirKey);
+    if (first) {
+      byRef.set(s.id, first);
+      byRef.set(s.name, first);
+      for (const e of envOf(s.labels)) addEnv(envs, e, first.name);
+      shared++;
+      continue;
+    }
+    const name = nameFor(s.name, taken);
+    const vendor = (s.vendor ?? "terraform").toLowerCase();
+    const tf = vendor === "terraform" || vendor === "opentofu";
+    if (!tf) nonTerraform++;
+    const m: ImportedMember = {
+      name,
+      dir: dirKey.startsWith("\0") ? name : dirKey,
+      kind: tf ? "terraform" : "other",
+      because: `Spacelift stack ${s.id}${s.space ? ` in space ${s.space}` : ""}${tf ? "" : `, ${vendor}`}`,
+    };
+    members.push(m);
+    byDir.set(dirKey, m);
+    byRef.set(s.id, m);
+    byRef.set(s.name, m);
+    for (const e of envOf(s.labels)) addEnv(envs, e, name);
+    contexts += s.contexts?.length ?? 0;
+  }
+
+  let dangling = 0;
+  for (const s of input.stacks) {
+    const consumer = byRef.get(s.id)!;
+    for (const dep of s.dependsOn ?? []) {
+      const producer = byRef.get(dep.stack);
+      if (!producer || producer === consumer) {
+        dangling++;
+        continue;
+      }
+      const outs = (dep.references ?? []).map((r) => r.outputName);
+      for (const o of outs.length > 0 ? outs : [APPLIED_OUTPUT]) addLink(consumer, producer, o);
+    }
+  }
+
+  const attached = new Map<string, string[]>();
+  for (const s of input.stacks) for (const p of s.policies ?? []) attached.set(p, [...(attached.get(p) ?? []), byRef.get(s.id)!.name]);
+  const records: ConstraintRecord[] = (input.policies ?? []).map((p) => ({
+    id: `spacelift-policy-${sanitizeName(p.name) || sanitizeName(p.id)}`,
+    kind: "constraint",
+    source: "spacelift",
+    title: p.name,
+    ...(p.type ? { policyKind: p.type } : {}),
+    appliesTo: attached.get(p.id) ?? [],
+  }));
+
+  const leftOut: LeftOut[] = [];
+  if (contexts > 0) leftOut.push({ what: "context attachments", count: contexts, why: "contexts hold variables and mounted files, which are never read" });
+  if (shared > 0) leftOut.push({ what: "stacks sharing a project root", count: shared, why: "a member is one directory; each folds into the first stack on it" });
+  if (dangling > 0) leftOut.push({ what: "stack dependencies", count: dangling, why: "the dependency's stack is not in the input, or is the stack itself" });
+  if (nonTerraform > 0) leftOut.push({ what: "non-Terraform stacks kept as other", count: nonTerraform, why: "only Terraform and OpenTofu stacks take the terraform kind" });
+  leftOut.push({ what: "worker pools, cloud integrations and run history", count: input.stacks.length, why: "not structure of the workspace" });
+
+  return finish("spacelift", options.name ?? input.account, members, { environments: envList(envs), records, leftOut, notes: [TF_NOTE] });
+}
+
+// ── Backstage ────────────────────────────────────────────────────────────────
+
+interface Entity {
+  apiVersion?: string;
+  kind?: string;
+  metadata?: { name?: string; namespace?: string };
+  spec?: { lifecycle?: string; dependsOn?: unknown; consumesApis?: unknown; providesApis?: unknown; owner?: string; system?: string };
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".chant"]);
+
+/** Every `catalog-info.yaml` under `root`, relative and `/`-separated. */
+export function findCatalogFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) walk(join(dir, e.name));
+      } else if (e.isFile() && /^catalog-info\.ya?ml$/.test(e.name)) {
+        out.push(relative(root, join(dir, e.name)).split("\\").join("/"));
+      }
+    }
+  };
+  if (existsSync(root)) walk(root);
+  return out.sort();
+}
+
+const refKey = (kind: string, ns: string | undefined, name: string): string => `${kind.toLowerCase()}:${ns ?? "default"}/${name}`;
+
+function asRefs(v: unknown): string[] {
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+}
+
+/** Normalize `name`, `kind:name` and `kind:ns/name` to `kind:ns/name`. */
+function normalizeRef(ref: string, defaultKind: string): string {
+  const m = /^(?:([A-Za-z]+):)?(?:([^/]+)\/)?(.+)$/.exec(ref.trim());
+  if (!m) return ref;
+  return refKey(m[1] ?? defaultKind, m[2], m[3]);
+}
+
+export function proposeFromBackstage(root: string, options: { name?: string } = {}): ImportProposal {
+  const files = findCatalogFiles(root);
+  const taken = new Set<string>();
+  const byRef = new Map<string, ImportedMember>();
+  const byDir = new Map<string, ImportedMember>();
+  const members: ImportedMember[] = [];
+  const entities: { entity: Entity; member?: ImportedMember; ref: string }[] = [];
+  const envs = new Map<string, string[]>();
+  const skipped = new Map<string, number>();
+  const bump = (k: string): void => void skipped.set(k, (skipped.get(k) ?? 0) + 1);
+
+  for (const file of files) {
+    let docs: unknown[];
+    try {
+      docs = yaml.loadAll(readFileSync(join(root, file), "utf-8"));
+    } catch {
+      bump("unreadable catalog-info.yaml");
+      continue;
+    }
+    const dir = cleanDir(dirname(file), "");
+    for (const doc of docs) {
+      const entity = doc as Entity;
+      const kind = entity?.kind;
+      const name = entity?.metadata?.name;
+      if (typeof kind !== "string" || typeof name !== "string") continue;
+      const ref = refKey(kind, entity.metadata?.namespace, name);
+      if (kind !== "Component" && kind !== "Resource") {
+        bump(kind);
+        entities.push({ entity, ref });
+        continue;
+      }
+      let member = byDir.get(dir);
+      if (member) {
+        // One member per directory: a second entity in the directory folds into the first.
+        byRef.set(ref, member);
+        bump(`${kind} sharing a directory with a member`);
+      } else {
+        member = {
+          name: nameFor(name, taken),
+          dir: dir === "" ? "." : dir,
+          kind: "other",
+          because: `Backstage ${kind.toLowerCase()} ${name}${entity.spec?.system ? ` of system ${entity.spec.system}` : ""}`,
+        };
+        members.push(member);
+        byDir.set(dir, member);
+        byRef.set(ref, member);
+        const lifecycle = entity.spec?.lifecycle;
+        if (lifecycle) addEnv(envs, lifecycle, member.name);
+      }
+      entities.push({ entity, member, ref });
+    }
+  }
+
+  const apiProviders = new Map<string, ImportedMember>();
+  for (const { entity, member } of entities) {
+    if (member) for (const api of asRefs(entity.spec?.providesApis)) apiProviders.set(normalizeRef(api, "api"), member);
+  }
+  let dangling = 0;
+  for (const { entity, member } of entities) {
+    if (!member) continue;
+    const wants: { producer: ImportedMember | undefined }[] = [
+      ...asRefs(entity.spec?.dependsOn).map((r) => ({ producer: byRef.get(normalizeRef(r, "component")) })),
+      ...asRefs(entity.spec?.consumesApis).map((r) => ({ producer: apiProviders.get(normalizeRef(r, "api")) })),
+    ];
+    for (const { producer } of wants) {
+      if (!producer || producer === member) {
+        dangling++;
+        continue;
+      }
+      addLink(member, producer, CATALOG_OUTPUT);
+    }
+  }
+
+  const leftOut: LeftOut[] = [...skipped].map(([what, count]) => ({
+    what,
+    count,
+    why: what.includes("sharing a directory") ? "a member is one directory; its dependsOn links fold into the first entity there" : "not a unit of code or infrastructure; its owner and system stay in the catalog",
+  }));
+  if (dangling > 0) leftOut.push({ what: "dependsOn and consumesApis references", count: dangling, why: "they name an entity outside the files read, or the entity itself" });
+  if (files.length === 0) leftOut.push({ what: "catalog-info.yaml files", count: 0, why: `none found under ${root}` });
+
+  const wsName = options.name ?? (root.split(/[\\/]/).filter(Boolean).pop() ?? "backstage");
+  return finish("backstage", wsName, members, { environments: envList(envs), records: [], leftOut, notes: [] });
+}
+
+// ── Reading an input file ────────────────────────────────────────────────────
+
+export function readInputFile(source: "tfc" | "spacelift", path: string): TfcInput | SpaceliftInput {
+  const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+  if (source === "tfc" && !Array.isArray(raw.workspaces)) throw new Error(`${path} has no "workspaces" array: it is not a Terraform Cloud export`);
+  if (source === "spacelift" && !Array.isArray(raw.stacks)) throw new Error(`${path} has no "stacks" array: it is not a Spacelift export`);
+  return raw as unknown as TfcInput | SpaceliftInput;
+}

package/src/workspace/init.test.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterAll, afterEach, beforeEach, describe, expect, test, vi } from "vitest";
@@ -56,6 +56,60 @@ const ACME = {
   "test/unit3/x.ts": "",
 };
 
+describe("proposeWorkspace with package kinds (#3179)", () => {
+  /** Install the real kinds files of the helm and k8s lexicons under node_modules, as a package manager would. */
+  function install(root: string): void {
+    for (const lexicon of ["helm", "k8s"]) {
+      const from = join(REPO, "lexicons", lexicon);
+      const to = join(root, "node_modules", "@intentius", `chant-lexicon-${lexicon}`);
+      mkdirSync(to, { recursive: true });
+      cpSync(join(from, "workspace-kinds.json"), join(to, "workspace-kinds.json"));
+      if (existsSync(join(from, "schemas"))) cpSync(join(from, "schemas"), join(to, "schemas"), { recursive: true });
+      const { name, version, exports, files } = JSON.parse(readFileSync(join(from, "package.json"), "utf-8"));
+      writeFileSync(join(to, "package.json"), JSON.stringify({ name, version, exports, files }));
+    }
+  }
+
+  const files = {
+    "charts/web/Chart.yaml": "apiVersion: v2\nname: web\nversion: 0.1.0\n",
+    "charts/web/values.yaml": "a: 1\n",
+    "deploy/prod/kustomization.yaml": "resources:\n  - ../base\n",
+    "gitops/guestbook.yaml": "apiVersion: argoproj.io/v1alpha1\nkind: Application\nmetadata:\n  name: guestbook\nspec: {}\n",
+    "tools/docs/package.json": pkg("docs-site"),
+  };
+
+  test("proposes a chart, an overlay and an Argo app as three typed members, with their packages pinned", () => {
+    const root = repo(files);
+    install(root);
+    const { declaration } = proposeWorkspace(root);
+    expect(declaration.members.map((m) => [m.dir, m.kind])).toEqual([
+      ["charts/web", "helm-chart"],
+      ["deploy/prod", "kustomize"],
+      ["gitops", "argo-app"],
+      ["tools/docs", "other"],
+    ]);
+    expect(declaration.pins?.map((p) => p.package)).toEqual(["@intentius/chant-lexicon-helm", "@intentius/chant-lexicon-k8s"]);
+    // The proposal is a valid declaration, and the kinds resolve through its pins.
+    expect(() => parseDeclaration(JSON.stringify(declaration), "chant.workspace.json")).not.toThrow();
+  });
+
+  test("pins only the packages whose kinds it used, and proposes nothing typed with no kinds installed", () => {
+    const root = repo({ "charts/web/Chart.yaml": files["charts/web/Chart.yaml"] });
+    install(root);
+    expect(proposeWorkspace(root).declaration.pins?.map((p) => p.package)).toEqual(["@intentius/chant-lexicon-helm"]);
+    const bare = repo(files);
+    const proposal = proposeWorkspace(bare).declaration;
+    expect(proposal.pins).toBeUndefined();
+    expect(proposal.members.map((m) => m.kind)).toEqual(["other"]);
+  });
+
+  test("a typed directory with a package.json is not also proposed as other", () => {
+    const root = repo({ "app/Chart.yaml": files["charts/web/Chart.yaml"], "app/package.json": pkg("app") });
+    install(root);
+    expect(proposeWorkspace(root).declaration.members.map((m) => [m.dir, m.kind])).toEqual([["app", "helm-chart"]]);
+  });
+});
+
 describe("proposeWorkspace (#2534)", () => {
   test("proposes members from projects, nested workspaces and packages, and example groups (ws-051)", () => {
     const root = repo(ACME, "git@github.com:acme/platform.git");

package/src/workspace/init.ts

@@ -48,10 +48,11 @@ import {
 } from "./declaration";
 import { expandGlob } from "./glob";
 import { setProperty } from "./json-edit";
-import { holdsChantProject } from "./kinds";
+import { dataExportTarget } from "./class-data";
+import { holdsChantProject, loadKindRegistry, resolveKind } from "./kinds";
 import { gitTop, skippedDir, workingTree, type WorkspaceTree } from "./tree";
 
-const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]\n       chant workspace init --profile ideation|app|infra [dir] [--name <name>] [--param name=<display name>] [--from <repo>@<ref>|<chant checkout>] [--yes]";
+const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]\n       chant workspace init --profile ideation|app|infra [dir] [--name <name>] [--param name=<display name>] [--from <repo>@<ref>|<chant checkout>] [--yes]\n       chant workspace init --from tfc|spacelift|backstage [dir] [--org <organization>] [--endpoint <url>] [--input <export.json>] [--token <token>] [--yes]";
 
 /** The profiles `--profile` takes (#3174), each a directory under {@link PROFILES_DIR} in the chant repository. */
 export const PROFILES = ["ideation", "app", "infra"] as const;
@@ -119,7 +120,7 @@ export interface StackProposal {
 export interface Proposal {
   root: string;
   /** The declaration as it would be written. */
-  declaration: { name: string; schema: 1; members: ProposedEntry[] };
+  declaration: { name: string; schema: 1; pins?: { package: string; version: string }[]; members: ProposedEntry[] };
   /** Directories leaving the root project, with the .ts source files each holds. */
   leaving: { dir: string; owner: string; files: string[] }[];
   /** One ownership stack per `chant` member, all distinct (ws-037). */
@@ -384,6 +385,33 @@ function groupName(glob: string): string {
 
 // ── The proposal ─────────────────────────────────────────────────────────────
 
+/**
+ * The packages installed at `root` that supply member kinds, as pins at their
+ * installed versions. A declaration only reads kinds from its pins, so a
+ * proposal that names a package's kind has to pin the package too.
+ */
+function installedKindPins(root: string): { package: string; version: string }[] {
+  const scope = join(root, "node_modules", "@intentius");
+  let names: string[];
+  try {
+    names = readdirSync(scope).sort();
+  } catch {
+    return [];
+  }
+  const pins: { package: string; version: string }[] = [];
+  for (const n of names) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(scope, n, "package.json"), "utf-8")) as Record<string, unknown>;
+      if (typeof pkg.name === "string" && typeof pkg.version === "string" && typeof dataExportTarget(pkg, "./workspace-kinds") === "string") {
+        pins.push({ package: pkg.name, version: pkg.version });
+      }
+    } catch {
+      // Not a package, or not readable: it supplies nothing.
+    }
+  }
+  return pins;
+}
+
 export function proposeWorkspace(root: string, options: { name?: string } = {}): Proposal {
   const tree = workingTree(root);
   const files = listFiles(root);
@@ -424,7 +452,26 @@ export function proposeWorkspace(root: string, options: { name?: string } = {}):
     [...matches].some((m) => isInside(d, m)) ||
     chantMembers.some((c) => isInside(d, c) || isInside(c, d)) ||
     exampleMatch(d) !== undefined;
-  const packages = outermost([...pkgDirs].filter((d) => d !== "" && !claimed(d)));
+  // A directory that an installed package's kind claims is a typed member
+  // (#3179), taking the place of `other` for the same directory. Members
+  // don't nest, so a typed member is the outermost one, and never sits inside
+  // a project or package that is a member itself.
+  const packageDirs = outermost([...pkgDirs].filter((d) => d !== "" && !claimed(d)));
+  const kindPins = installedKindPins(root);
+  const kindRegistry = kindPins.length > 0 ? loadKindRegistry(kindPins.map((p) => ({ ...p, path: null, integrity: null })), root).registry : undefined;
+  const typed = new Map<string, string>();
+  if (kindRegistry) {
+    const winners = new Map<string, string>();
+    const others = [...configDirs, ...nested, ...packageDirs];
+    for (const d of new Set(files.map(dirOf))) {
+      if (d === "" || claimed(d) || configDirs.has(d) || nested.includes(d)) continue;
+      if (others.some((o) => o !== d && isInside(d, o))) continue;
+      const winner = resolveKind(kindRegistry, tree, d).winner;
+      if (winner && winner.source !== "builtin") winners.set(d, winner.name);
+    }
+    for (const d of outermost(winners.keys())) typed.set(d, winners.get(d)!);
+  }
+  const packages = packageDirs.filter((d) => ![...typed.keys()].some((t) => isInside(d, t)));
 
   const taken = new Set<string>([name]);
   const entries: (ProposedEntry & { sort: string })[] = [];
@@ -440,6 +487,9 @@ export function proposeWorkspace(root: string, options: { name?: string } = {}):
       because: npmWorkspaces.has(d) ? "an npm workspace package with no chant project" : "an npm package with no chant project",
     });
   }
+  for (const [d, kind] of typed) {
+    entries.push({ sort: d, name: uniqueName(memberName(tree, d, name), taken), dir: d, kind });
+  }
   entries.sort((a, b) => (a.sort < b.sort ? -1 : a.sort > b.sort ? 1 : 0));
   taken.delete(name);
 
@@ -453,9 +503,12 @@ export function proposeWorkspace(root: string, options: { name?: string } = {}):
     .map(([n, globs]) => ({ name: uniqueName(n, taken), kind: "examples", glob: globs.length === 1 ? globs[0] : globs }))
     .sort((a, b) => ([a.glob].flat()[0] < [b.glob].flat()[0] ? -1 : 1));
 
+  const usedSources = new Set([...typed.values()].map((k) => kindRegistry!.get(k)!.source));
+  const pins = kindPins.filter((p) => usedSources.has(p.package));
   const declaration = {
     name,
     schema: 1 as const,
+    ...(pins.length > 0 ? { pins } : {}),
     members: [...entries.map(({ sort: _sort, ...e }) => e), ...groups],
   };
 
@@ -575,6 +628,15 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
   }
 
   if (args.profile !== undefined) return initProfile(args, root);
+  // #3178: --from tfc|spacelift|backstage proposes from structure held outside the repository.
+  const { isImportSource, runImportInit, IMPORT_USAGE } = await import("./import-init");
+  if (args.migrateFrom !== undefined) {
+    if (!isImportSource(args.migrateFrom)) {
+      console.error(formatError({ message: `--from ${JSON.stringify(args.migrateFrom)} is not a source; the sources are tfc, spacelift, backstage`, hint: IMPORT_USAGE }));
+      return 1;
+    }
+    return runImportInit(args.migrateFrom, root, args);
+  }
 
   let proposal: Proposal;
   try {