@intentius/chant 0.124.48 → 0.124.50

package/dist/workspace/import-source.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `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.
+ */
+export declare const IMPORT_SOURCES: readonly ["tfc", "spacelift", "backstage"];
+export type ImportSource = (typeof IMPORT_SOURCES)[number];
+/** The output every imported producer exposes when its source names none: "this member was applied". */
+export declare const APPLIED_OUTPUT = "applied";
+/** The output a Backstage entity exposes to the entities that depend on it. */
+export declare const CATALOG_OUTPUT = "catalog";
+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;
+    }[];
+}
+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[];
+}
+export declare function proposeFromTfc(input: TfcInput, options?: {
+    name?: string;
+}): ImportProposal;
+export declare function proposeFromSpacelift(input: SpaceliftInput, options?: {
+    name?: string;
+}): ImportProposal;
+/** Every `catalog-info.yaml` under `root`, relative and `/`-separated. */
+export declare function findCatalogFiles(root: string): string[];
+export declare function proposeFromBackstage(root: string, options?: {
+    name?: string;
+}): ImportProposal;
+export declare function readInputFile(source: "tfc" | "spacelift", path: string): TfcInput | SpaceliftInput;
+//# sourceMappingURL=import-source.d.ts.map

package/dist/workspace/import-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-source.d.ts","sourceRoot":"","sources":["../../src/workspace/import-source.ts"],"names":[],"mappings":"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"}

package/dist/workspace/import-source.js

@@ -0,0 +1,370 @@
+/**
+ * `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.js";
+import { sanitizeName } from "./init.js";
+export const IMPORT_SOURCES = ["tfc", "spacelift", "backstage"];
+/** 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";
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function nameFor(raw, taken) {
+    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, fallback) {
+    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) {
+    return (tags ?? []).map((t) => ENV_TAG.exec(t)?.[1]?.trim()).filter((e) => !!e);
+}
+function addEnv(map, env, member) {
+    const list = map.get(env) ?? [];
+    if (!list.includes(member))
+        list.push(member);
+    map.set(env, list);
+}
+function envList(map) {
+    return [...map].map(([name, members]) => ({ name, members })).sort((a, b) => a.name.localeCompare(b.name));
+}
+function addLink(member, producer, output) {
+    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, workspaceName, members, parts) {
+    const declaration = { name: nameFor(workspaceName, new Set()), schema: 1, 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, options = {}) {
+    const taken = new Set();
+    const byRef = new Map();
+    const members = [];
+    const projects = new Map((input.projects ?? []).map((p) => [p.id, p.name]));
+    const envs = new Map();
+    let variables = 0;
+    let sensitive = 0;
+    let vcs = 0;
+    let notifications = 0;
+    const byDir = new Map();
+    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 = {
+            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 = (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),
+    }));
+    const 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, options = {}) {
+    const taken = new Set();
+    const byRef = new Map();
+    const members = [];
+    const envs = new Map();
+    let nonTerraform = 0;
+    let contexts = 0;
+    const byDir = new Map();
+    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 = {
+            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();
+    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 = (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 = [];
+    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] });
+}
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".chant"]);
+/** Every `catalog-info.yaml` under `root`, relative and `/`-separated. */
+export function findCatalogFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        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, ns, name) => `${kind.toLowerCase()}:${ns ?? "default"}/${name}`;
+function asRefs(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/** Normalize `name`, `kind:name` and `kind:ns/name` to `kind:ns/name`. */
+function normalizeRef(ref, defaultKind) {
+    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, options = {}) {
+    const files = findCatalogFiles(root);
+    const taken = new Set();
+    const byRef = new Map();
+    const byDir = new Map();
+    const members = [];
+    const entities = [];
+    const envs = new Map();
+    const skipped = new Map();
+    const bump = (k) => void skipped.set(k, (skipped.get(k) ?? 0) + 1);
+    for (const file of files) {
+        let docs;
+        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;
+            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();
+    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 = [
+            ...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 = [...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, path) {
+    const raw = JSON.parse(readFileSync(path, "utf-8"));
+    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;
+}

package/dist/workspace/init.d.ts

@@ -74,6 +74,10 @@ export interface Proposal {
     declaration: {
         name: string;
         schema: 1;
+        pins?: {
+            package: string;
+            version: string;
+        }[];
         members: ProposedEntry[];
     };
     /** Directories leaving the root project, with the .ts source files each holds. */

package/dist/workspace/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/workspace/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AActD,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI7E,mHAAmH;AACnH,eAAO,MAAM,QAAQ,YAAI,UAAU,EAAE,KAAK,EAAE,OAAO,CAAU,CAAC;AAC9D,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,YAAY,iCAAiC,CAAC;AAE3D,yFAAyF;AACzF,eAAO,MAAM,aAAa,uCAAuC,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGjG;AAoBD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,uGAAuG;IACvG,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC5C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,OAAO,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IACnE,kFAAkF;IAClF,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC3D,qEAAqE;IACrE,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAiDD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQhD;AAuDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAkBvI;AASD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,aAAa,EAAE,CAuB1H;AAoFD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,CAsFxF;AA4ED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoE3E"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/workspace/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAetD,OAAO,EAAmC,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI7E,mHAAmH;AACnH,eAAO,MAAM,QAAQ,YAAI,UAAU,EAAE,KAAK,EAAE,OAAO,CAAU,CAAC;AAC9D,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,YAAY,iCAAiC,CAAC;AAE3D,yFAAyF;AACzF,eAAO,MAAM,aAAa,uCAAuC,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGjG;AAoBD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,uGAAuG;IACvG,MAAM,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC5C;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAAC,OAAO,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IAClH,kFAAkF;IAClF,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAC3D,qEAAqE;IACrE,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAiDD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQhD;AAuDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAkBvI;AASD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,aAAa,EAAE,CAuB1H;AA+GD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,QAAQ,CA+GxF;AA4ED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6E3E"}

package/dist/workspace/init.js

@@ -37,9 +37,10 @@ import { formatError, formatSuccess } from "../cli/format.js";
 import { DECLARATION_FILES, NAME_PATTERN, parseDeclaration, resolveGroups, rootExclusions, WorkspaceReadError, isInside, readerVersion, } from "./declaration.js";
 import { expandGlob } from "./glob.js";
 import { setProperty } from "./json-edit.js";
-import { holdsChantProject } from "./kinds.js";
+import { dataExportTarget } from "./class-data.js";
+import { holdsChantProject, loadKindRegistry, resolveKind } from "./kinds.js";
 import { gitTop, skippedDir, workingTree } from "./tree.js";
-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"];
 /** Where the profiles live in the chant repository. */
@@ -335,6 +336,34 @@ function groupName(glob) {
     return sanitizeName([...words, base].join("-")) || base;
 }
 // ── 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) {
+    const scope = join(root, "node_modules", "@intentius");
+    let names;
+    try {
+        names = readdirSync(scope).sort();
+    }
+    catch {
+        return [];
+    }
+    const pins = [];
+    for (const n of names) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(scope, n, "package.json"), "utf-8"));
+            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, options = {}) {
     const tree = workingTree(root);
     const files = listFiles(root);
@@ -377,7 +406,30 @@ export function proposeWorkspace(root, options = {}) {
         [...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();
+    if (kindRegistry) {
+        const winners = new Map();
+        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([name]);
     const entries = [];
     if (configDirs.has(""))
@@ -395,6 +447,9 @@ export function proposeWorkspace(root, options = {}) {
             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);
     const memberDirs = entries.map((e) => (e.dir === "." ? "" : e.dir));
@@ -406,9 +461,12 @@ export function proposeWorkspace(root, options = {}) {
     const groups = [...byGroup]
         .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,
+        ...(pins.length > 0 ? { pins } : {}),
         members: [...entries.map(({ sort: _sort, ...e }) => e), ...groups],
     };
     // Read the proposal back through the real reader: it must be a valid
@@ -527,6 +585,15 @@ export async function runWorkspaceInit(ctx) {
     }
     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.js");
+    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;
     try {
         proposal = proposeWorkspace(root, { name: args.selectName });