@dharta/cli 0.6.77

package/dist/commands/setup.js

@@ -0,0 +1,949 @@
+import { constants, existsSync, promises as fs, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import * as path from "node:path";
+import { findGitRoot, scanAgentFolders, renderTable, describeFolder } from "../setup-scan.js";
+import { renderManifest, patchManifest } from "../manifest.js";
+import { deriveSlug, validateAgentName } from "../agent.js";
+import { defaultGitRunner, rejectOverlappingAgentRoots } from "./deploy.js";
+import { closestChoice, normalizeNonBlank } from "../validators.js";
+import { DEFAULT_CREATE_HARNESS, hasAgentMarker } from "../harnesses.js";
+const METHODS = ["git", "folder"];
+const METHOD_INPUTS = [...METHODS, "github"];
+const CI_PROVIDERS = ["github"];
+const MANAGED_WORKFLOW_MARKER = "# Dharta managed workflow. Generated by dharta setup (format v1).";
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+export async function setup(pathArg, opts = {}) {
+    const cwd = path.resolve(opts.cwd ?? ".");
+    const git = opts.gitRunner ?? defaultGitRunner;
+    const log = opts.log ?? ((line) => console.error(line));
+    const ask = opts.yes ? undefined : opts.ask;
+    const pathInput = pathArg === undefined ? undefined : normalizeNonBlank(pathArg, "path");
+    const parsedMethod = parseMethod(opts.method); // validate configuration up front
+    const forcedMethod = parsedMethod.method;
+    const ci = parseCi(opts.ci) ?? parsedMethod.ci;
+    if (opts.enable && opts.disable)
+        throw new Error("Use either --enable or --disable, not both.");
+    if (opts.name !== undefined)
+        validateAgentName(opts.name, "--name");
+    // Resolve and validate an explicit target before setup can initialize git or
+    // write anything. Besides avoiding a stray .git on typos, this establishes a
+    // lexical + realpath boundary that a symlink cannot redirect later writes
+    // through.
+    let gitRoot = findGitRoot(cwd);
+    await validateExplicitSetupPath(cwd, pathInput, gitRoot ?? cwd);
+    if (parsedMethod.legacyGithub) {
+        log("Compatibility: --method github now means --method folder plus --ci github. " +
+            "Prefer the two explicit options in scripts.");
+    }
+    // --- 1. git context (needed by git transport and GitHub automation) -----
+    const containingPlainAgent = !gitRoot && !pathInput ? nearestAgentMarkerDir(cwd) : undefined;
+    const localSetupRoot = containingPlainAgent ?? cwd;
+    let gitInitialized = false;
+    const existingMethod = !gitRoot && !forcedMethod
+        ? await inferExistingMethodWithoutGit(localSetupRoot, pathInput)
+        : undefined;
+    const needsGit = ci === "github" || (forcedMethod ?? existingMethod) !== "folder";
+    if (!gitRoot && needsGit) {
+        const rel = relLabel(localSetupRoot);
+        const create = ask
+            ? yesNoCancel(await ask(`No git here. Create git in ${rel} ? [Yes] / [no] / [cancel]  `))
+            : "yes"; // non-interactive default takes the [Yes] (or pass --method folder)
+        if (create === "cancel")
+            throw new Error("setup canceled.");
+        if (create === "no" && ci === "github") {
+            throw new Error("--ci github requires a git repo. Initialize git, then run setup again.");
+        }
+        if (create === "yes") {
+            await run(git, ["-C", localSetupRoot, "init", "-b", "main"], "git init");
+            gitRoot = localSetupRoot;
+            gitInitialized = true;
+            log(`Initialized a git repo in ${rel}.`);
+        }
+    }
+    const scanRoot = gitRoot ?? containingPlainAgent ?? cwd;
+    const hasGit = !!gitRoot;
+    // --- 2. scan for agent folders -----------------------------------------
+    const folders = await scanAgentFolders(scanRoot, { isGitRepo: hasGit });
+    const shared = { cwd, git, hasGit, scanRoot, gitInitialized, forcedMethod, ci, ask, log };
+    // The nearest containing agent always wins, even if it is deep or ignored
+    // and therefore absent from the repo-wide discovery list. Setup from inside
+    // an agent must never fall through to a sibling selection.
+    if (!pathInput) {
+        const containingDir = nearestAgentMarkerDir(cwd, gitRoot ?? undefined);
+        if (containingDir) {
+            const target = folders.find((folder) => folder.dir === containingDir) ??
+                await describeFolder(containingDir, path.relative(scanRoot, containingDir));
+            requireAgent(target, pathInput);
+            return configureAgent(target, shared, opts);
+        }
+    }
+    // --- 3. interactive + several agents: select exactly one ----------------
+    // Setup is agent-scoped, just like deploy. Standing inside an agent selects
+    // it immediately. At an ambiguous repo root, show one menu and configure the
+    // single choice; configuring siblings requires explicit repeat invocations.
+    if (ask && !pathInput && folders.length >= 2) {
+        const target = await pickOneAgent(folders, shared);
+        if (!target)
+            return snapshotResult(folders[0], shared);
+        return configureAgent(target, shared, opts);
+    }
+    // --- single agent / explicit path / non-interactive --------------------
+    if (ask && folders.length > 0) {
+        log("");
+        log(renderTable(folders));
+        log("");
+    }
+    const target = await pickFolder(pathInput, folders, scanRoot, cwd, ask);
+    requireAgent(target, pathInput);
+    return configureAgent(target, shared, opts);
+}
+function nearestAgentMarkerDir(start, boundary) {
+    let dir = path.resolve(start);
+    const stop = boundary === undefined ? undefined : path.resolve(boundary);
+    for (;;) {
+        if (hasAgentMarker(dir))
+            return dir;
+        if (stop && dir === stop)
+            return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+// setup configures an EXISTING agent; scaffolding a brand-new folder is
+// `dharta create`'s job (RFC 0024). A folder with no harness or karta marker
+// has no agent to configure - send them to create.
+function requireAgent(target, pathArg) {
+    if (hasAgentMarker(target.dir))
+        return;
+    const here = target.rel === "." ? "this folder" : target.rel;
+    throw new Error(`No agent to configure in ${here}. Create one first with \`dharta create${pathArg ? ` ${pathArg}` : ""}\`.`);
+}
+// Configure ONE agent: name, deploy gate, delivery method, then write the
+// self-documenting dharta.toml and apply the method action.
+async function configureAgent(target, s, opts) {
+    const { cwd, hasGit, scanRoot, gitInitialized, ask, log } = s;
+    // Discovery is read-only and may encounter paths supplied by the working
+    // tree. Re-establish the selected agent boundary before prompts or writes so
+    // an explicit or discovered symlink can never become a write target.
+    await validateSelectedAgentRoot(scanRoot, target.dir, target.rel);
+    const defaultName = target.name ?? deriveSlug(path.basename(target.dir));
+    const name = validateAgentName(opts.name === undefined
+        ? ((ask ? (await ask(`Agent name [${defaultName}]:  `)).trim() : "") || defaultName)
+        : opts.name, "agent name");
+    // Default to the EXISTING gate so re-running setup on an enabled agent does
+    // not silently disable it; a brand-new agent has deployEnabled = false, so
+    // D6's fail-safe default still holds.
+    let deploy;
+    if (opts.enable)
+        deploy = true;
+    else if (opts.disable)
+        deploy = false;
+    else if (ask) {
+        const defaultDeploy = target.configured ? target.deployEnabled : false;
+        const hint = defaultDeploy ? "Y/n" : "y/N";
+        deploy = yesNo(await ask(`Enable deploy for this agent? [${hint}]  `), defaultDeploy);
+    }
+    else
+        deploy = target.deployEnabled;
+    // An explicit option changes the transport; otherwise preserve the method
+    // already configured for this agent. Only an unconfigured agent falls back
+    // to the repo-shaped default / interactive choice.
+    let method = s.forcedMethod ?? target.deployMethod;
+    if (!method)
+        method = ask ? await askMethod(ask, hasGit) : hasGit ? "git" : "folder";
+    if (!hasGit)
+        method = "folder"; // folder is forced without a git repo
+    // Enforce the same one-manifest-per-release-root invariant as deploy before
+    // either local artifact is written. A parent and child dharta.toml would make
+    // ownership of the child's files ambiguous regardless of transport or CI.
+    await rejectOverlappingAgentRoots(target.dir, s.git);
+    await rejectDuplicateAgentSlug(scanRoot, target.dir, name, hasGit);
+    const workflow = s.ci === "github"
+        ? githubWorkflowTarget(scanRoot, target.dir, name, method, await currentGitBranch(s.git, scanRoot))
+        : undefined;
+    let workflowState;
+    if (workflow) {
+        if (!hasGit)
+            throw new Error("--ci github requires a git repo.");
+        await validateWorkflowTarget(workflow);
+        workflowState = await existingWorkflowState(workflow, log);
+        if (workflowState !== "custom") {
+            await rejectGitignoredSetupFile(s.git, scanRoot, workflow.dest, workflow.rel);
+        }
+    }
+    const manifestPath = path.join(target.dir, "dharta.toml");
+    await validateSafeWriteTarget(target.dir, manifestPath, "dharta.toml", false);
+    if (hasGit) {
+        await rejectGitignoredSetupFile(s.git, scanRoot, manifestPath, path.relative(scanRoot, manifestPath));
+    }
+    const existingManifest = await lstatIfPresent(manifestPath);
+    const scaffolded = existingManifest === undefined;
+    if (existingManifest) {
+        const patched = patchManifest(await fs.readFile(manifestPath, "utf8"), {
+            name,
+            deploy,
+            deployMethod: method,
+        });
+        await safeAtomicWriteFile(target.dir, manifestPath, "dharta.toml", patched);
+    }
+    else {
+        await safeAtomicWriteFile(target.dir, manifestPath, "dharta.toml", renderManifest({
+            name,
+            deploy,
+            deployMethod: method,
+            harness: target.harnessType ?? DEFAULT_CREATE_HARNESS,
+        }));
+    }
+    log(`${scaffolded ? "Wrote" : "Updated"} ${path.relative(cwd, manifestPath) || "dharta.toml"} ` +
+        `(name = ${name}, deploy = ${deploy}, deploy_method = ${method}).`);
+    applyMethod(method, { deploy, log });
+    const workflowScaffolded = workflow
+        ? await scaffoldGithubWorkflow(workflow, workflowState, log)
+        : false;
+    return {
+        folder: target.rel,
+        name,
+        deploy,
+        method,
+        ci: s.ci,
+        manifestPath,
+        scaffolded,
+        workflowScaffolded,
+        gitInitialized,
+    };
+}
+async function pickOneAgent(initial, s) {
+    const { scanRoot, hasGit, ask, log } = s;
+    const view = await Promise.all(initial.map((folder) => describeFolder(folder.dir, folder.rel)));
+    log("");
+    log(`Agents in ${hasGit ? "this repo" : "this folder"} (${scanRoot}):`);
+    log("");
+    log(renderMenu(view, null));
+    log("");
+    return selectAgent(ask, view, log);
+}
+// The agent folder the user is standing in: an exact cwd match, else the
+// deepest agent that contains cwd. null when cwd is outside every agent.
+function currentAgentDir(folders, cwd) {
+    const containing = folders
+        .filter((f) => f.dir === cwd || cwd.startsWith(f.dir + path.sep))
+        .sort((a, b) => b.dir.length - a.dir.length);
+    return containing[0]?.dir ?? null;
+}
+// Numbered agent menu: the current folder is prefixed [current], and a final
+// `q` row cancels this invocation.
+function renderMenu(folders, currentDir) {
+    const headers = ["#", "AGENT FOLDER", "NAME", "HARNESS", "CONFIGURED", "DEPLOY", "METHOD"];
+    const rows = folders.map((f, i) => [
+        String(i + 1),
+        `${f.dir === currentDir ? "[current] " : ""}${f.rel === "." ? "./ (repo root)" : `./${f.rel}`}`,
+        f.name ?? "-",
+        f.harnessType ?? "-",
+        f.configured ? "yes" : "no",
+        f.configured ? (f.deployEnabled ? "enabled" : "disabled") : "-",
+        f.deployMethod ?? "-",
+    ]);
+    const quit = ["q", "quit", "", "", "", "", ""];
+    const widths = headers.map((_, i) => Math.max(...[headers, ...rows, quit].map((r) => r[i].length)));
+    const fmt = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+    return [fmt(headers), ...rows.map(fmt), fmt(quit)].join("\n");
+}
+// Read one menu choice: a number, or 'q' to quit. An empty answer quits because
+// an ambiguous repository root has no safe implicit agent selection.
+async function selectAgent(ask, folders, log) {
+    for (;;) {
+        const choice = (await ask("Select one agent to set up, or q to quit [q]:  ")).trim().toLowerCase() || "q";
+        if (choice === "q" || choice === "quit")
+            return null;
+        const n = Number(choice);
+        if (Number.isInteger(n) && n >= 1 && n <= folders.length)
+            return folders[n - 1];
+        log(`Enter a number 1-${folders.length}, or q to quit.`);
+    }
+}
+// A read-only SetupResult for "quit before configuring anything" - only used to
+// satisfy the return type; the interactive caller never reads it.
+function snapshotResult(f, s) {
+    return {
+        folder: f.rel,
+        name: f.name ?? deriveSlug(path.basename(f.dir)),
+        deploy: f.deployEnabled,
+        method: f.deployMethod ?? (s.hasGit ? "git" : "folder"),
+        ci: s.ci,
+        manifestPath: path.join(f.dir, "dharta.toml"),
+        scaffolded: false,
+        workflowScaffolded: false,
+        gitInitialized: s.gitInitialized,
+    };
+}
+function parseMethod(raw) {
+    if (raw === undefined)
+        return { legacyGithub: false };
+    const normalized = normalizeNonBlank(raw, "--method");
+    // Backward compatibility for the old three-way transport switch. GitHub is
+    // automation, and the workflow it historically generated used folder
+    // upload, so preserve that behavior while making the two decisions explicit.
+    if (normalized === "github") {
+        return { method: "folder", ci: "github", legacyGithub: true };
+    }
+    if (!METHODS.includes(normalized)) {
+        const suggestion = closestChoice(normalized, METHOD_INPUTS);
+        throw new Error(`Unknown --method '${normalized}'. Use git or folder.` +
+            (suggestion ? ` Did you mean ${suggestion}?` : ""));
+    }
+    return { method: normalized, legacyGithub: false };
+}
+function parseCi(raw) {
+    if (raw === undefined)
+        return undefined;
+    const normalized = normalizeNonBlank(raw, "--ci");
+    if (!CI_PROVIDERS.includes(normalized)) {
+        const suggestion = closestChoice(normalized, CI_PROVIDERS);
+        throw new Error(`Unknown --ci '${normalized}'. Use github.` +
+            (suggestion ? ` Did you mean ${suggestion}?` : ""));
+    }
+    return normalized;
+}
+// Before setup decides whether to initialize git, honor a persisted folder
+// method for the obvious single-agent / explicit-path cases. This prevents a
+// routine setup re-run from changing a plain-folder project's repo shape.
+async function inferExistingMethodWithoutGit(cwd, pathArg) {
+    if (pathArg) {
+        return (await describeFolder(path.resolve(cwd, pathArg), pathArg)).deployMethod;
+    }
+    const folders = await scanAgentFolders(cwd, { isGitRepo: false });
+    if (folders.length === 1)
+        return folders[0].deployMethod;
+    if (folders.length > 1 && folders.every((folder) => folder.deployMethod === "folder")) {
+        return "folder";
+    }
+    return undefined;
+}
+async function validateExplicitSetupPath(cwd, pathArg, boundary) {
+    if (!pathArg)
+        return;
+    const target = path.resolve(cwd, pathArg);
+    try {
+        await validateExistingDirectoryTree(boundary, target, `Cannot set up ${pathArg}`);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            throw new Error(`Cannot set up ${pathArg}: that directory does not exist. ` +
+                `Create an agent first with \`dharta create ${pathArg}\`.`);
+        }
+        if (code === "ENOTDIR") {
+            throw new Error(`Cannot set up ${pathArg}: a parent path is not a directory.`);
+        }
+        throw error;
+    }
+    if (!hasAgentMarker(target)) {
+        throw new Error(`Cannot set up ${pathArg}: no agent was found there. ` +
+            `Create one first with \`dharta create ${pathArg}\`.`);
+    }
+}
+async function validateSelectedAgentRoot(scanRoot, agentDir, rel) {
+    const label = rel === "." ? "selected agent root" : `selected agent root '${rel}'`;
+    await validateExistingDirectoryTree(scanRoot, agentDir, `Cannot use ${label}`);
+}
+// Resolve the agent folder: an explicit path, the sole candidate, an
+// interactive pick, or (non-interactive + ambiguous) a loud error.
+async function pickFolder(pathArg, folders, scanRoot, cwd, ask) {
+    if (pathArg) {
+        const requested = path.resolve(cwd, pathArg);
+        const [scanRootReal, requestedReal] = await Promise.all([fs.realpath(scanRoot), fs.realpath(requested)]);
+        const realRelative = containedRelativePath(scanRootReal, requestedReal);
+        // Use the scan root's spelling for all later reads/writes. This preserves
+        // harmless platform aliases such as macOS /var -> /private/var while
+        // removing any caller-supplied symlink component from the writable path.
+        const dir = realRelative === undefined ? requested : path.resolve(scanRoot, realRelative);
+        const match = folders.find((f) => f.dir === dir);
+        if (match)
+            return match;
+        // Not surfaced by the scan (deep / untracked): describe it directly so an
+        // existing dharta.toml's name + deploy are read, not silently reset to the
+        // folder slug - which would rename the agent and change its deploy slug.
+        return describeFolder(dir, path.relative(scanRoot, dir));
+    }
+    const current = currentAgentDir(folders, cwd);
+    if (current)
+        return folders.find((folder) => folder.dir === current);
+    if (folders.length === 1)
+        return folders[0];
+    if (folders.length === 0) {
+        // No marker folder found - configure the scan root itself.
+        return { dir: scanRoot, rel: ".", configured: false, deployEnabled: false };
+    }
+    if (!ask) {
+        throw new Error("Multiple agent folders here. Pass a [path] to pick one, e.g. `dharta setup ./support-bot`.");
+    }
+    const answer = (await ask("Configure which folder? (path)  ")).trim();
+    const dir = path.resolve(scanRoot, answer);
+    const match = folders.find((f) => f.dir === dir || f.rel === answer);
+    if (!match)
+        throw new Error(`No agent folder matching '${answer}'.`);
+    return match;
+}
+async function askMethod(ask, hasGit) {
+    const def = hasGit ? "git" : "folder";
+    const a = (await ask(`Deploy method - git (push) / folder (upload) [${def}]:  `)).trim().toLowerCase();
+    return METHODS.includes(a) ? a : def;
+}
+function applyMethod(method, o) {
+    const deployHint = o.deploy ? "`dharta deploy`" : "enable it (deploy = true), then `dharta deploy`";
+    switch (method) {
+        case "git":
+            // The hosted repo + the `dharta` remote are provisioned at deploy time
+            // (dharta deploy self-provisions), keeping setup destination-agnostic.
+            o.log(`Method: git. Deploy with ${deployHint} - it provisions the hosted repo and wires the 'karta' remote on first run. ` +
+                "After that, 'dharta deploy' remains the agent-scoped path. A direct deploy-branch push (for example, 'git push dharta main') is a compatibility shortcut only for repos with one enabled agent.");
+            return;
+        case "folder":
+            o.log(`Method: folder. Deploy with ${deployHint} - it uploads only this agent folder as a tarball.`);
+            return;
+    }
+}
+function githubWorkflowTarget(repoRoot, agentDirectory, name, method, branch) {
+    const relative = path.relative(repoRoot, agentDirectory);
+    if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        throw new Error("--ci github requires the agent folder to be inside the git repo.");
+    }
+    const agentDir = relative === "" ? "." : relative.split(path.sep).join("/");
+    if (agentDir.includes("${{")) {
+        throw new Error("--ci github cannot generate a safe workflow for an agent path containing '${{'. " +
+            "Rename the folder, then run setup again.");
+    }
+    const slug = deriveSlug(name);
+    const rel = `.github/workflows/dharta-${slug}.yml`;
+    const secretName = `DHARTA_API_KEY_${slug.replaceAll("-", "_").toUpperCase()}`;
+    return { repoRoot, slug, method, branch, secretName, agentDir, rel, dest: path.join(repoRoot, rel) };
+}
+async function currentGitBranch(git, repoRoot) {
+    const result = await git(["-C", repoRoot, "symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const branch = result.stdout.trim();
+    if (result.code !== 0 || branch.length === 0 || branch.match(/[\0\r\n]/)) {
+        throw new Error("--ci github needs a checked-out branch so setup can generate the correct push trigger. " +
+            "Check out the deploy branch, then run setup again.");
+    }
+    if (branch.includes("${{")) {
+        throw new Error("--ci github cannot generate a safe workflow for a branch containing '${{'. " +
+            "Check out a different deploy branch, then run setup again.");
+    }
+    return branch;
+}
+async function rejectDuplicateAgentSlug(scanRoot, targetDir, name, isGitRepo) {
+    const slug = deriveSlug(name);
+    const folders = isGitRepo
+        ? await scanAgentFolders(scanRoot, { isGitRepo: true })
+        : await recursiveConfiguredFolders(scanRoot);
+    const conflict = folders.find((folder) => path.resolve(folder.dir) !== path.resolve(targetDir) &&
+        folder.name !== undefined && deriveSlug(folder.name) === slug);
+    if (!conflict)
+        return;
+    throw new Error(`Agent name '${name}' resolves to slug '${slug}', already used by ${conflict.rel}. ` +
+        "Choose unique agent names before setup; Dharta deploy identity is the derived slug.");
+}
+async function recursiveConfiguredFolders(root) {
+    const folders = [];
+    const walk = async (dir) => {
+        if (existsSync(path.join(dir, "dharta.toml"))) {
+            folders.push(await describeFolder(dir, path.relative(root, dir) || "."));
+        }
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name === "node_modules" || entry.name.startsWith("."))
+                continue;
+            await walk(path.join(dir, entry.name));
+        }
+    };
+    await walk(path.resolve(root));
+    return folders;
+}
+// GitHub is an automation layer, not a third persisted transport. Each agent
+// owns one path-filtered workflow and one named secret, so changing support
+// cannot trigger billing and concurrent runs for the same agent stay ordered.
+// The job pins the method rendered by setup so its checkout, concurrency, and
+// credential scope cannot drift from the actual command. Setup does not mint
+// credentials; it explains the scope required by that method.
+async function scaffoldGithubWorkflow(target, state, log) {
+    if (state === "custom")
+        return false;
+    await safeAtomicWriteFile(target.repoRoot, target.dest, target.rel, renderDeployWorkflow(target));
+    log(`CI: github. ${state === "generated" ? "Updated" : "Wrote"} ${target.rel} for ${target.agentDir}.`);
+    log(`  This workflow is pinned to --mode ${target.method}. To change methods, rerun setup with ` +
+        "--ci github and rotate the agent's CI secret for the new scope.");
+    const scope = target.method === "folder" ? "releases:write" : "source_repos:write";
+    log(`  To let CI deploy, add a ${scope} key as the ${target.secretName} repo secret:`);
+    log(`    dharta keys create ci-${target.slug} --scope ${scope}`);
+    log("    (requires an active key with keys:write; dashboard creation also works)");
+    log(`    gh secret set ${target.secretName}  # or add it in repo Settings > Secrets`);
+    log("  Then push a change to this agent folder, or run the workflow manually.");
+    return true;
+}
+async function validateWorkflowTarget(target) {
+    // `target.dest` is always repo/.github/workflows/file. Derive the workflow
+    // directory without trusting a caller-supplied relative path.
+    const workflowsDir = path.dirname(target.dest);
+    await validateSafeWriteTarget(target.repoRoot, target.dest, target.rel, false);
+    await rejectLegacyRepoWorkflow(workflowsDir, target.dest);
+    await rejectConflictingGeneratedWorkflow(workflowsDir, target);
+}
+async function rejectConflictingGeneratedWorkflow(workflowsDir, target) {
+    let entries;
+    try {
+        entries = await fs.readdir(workflowsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const agentMarker = `# Agent directory: ${JSON.stringify(target.agentDir)}.`;
+    const unpinnedCommand = `dharta deploy --dir ${shellQuote(target.agentDir)}`;
+    for (const entry of entries) {
+        if (!entry.isFile() || !(entry.name.endsWith(".yml") || entry.name.endsWith(".yaml")))
+            continue;
+        const dest = path.join(workflowsDir, entry.name);
+        const content = await fs.readFile(dest, "utf8");
+        if (!isManagedWorkflow(content))
+            continue;
+        const deploysTarget = content.includes(agentMarker) || content.includes(unpinnedCommand);
+        if (path.resolve(dest) === path.resolve(target.dest) && !deploysTarget) {
+            throw new Error(`${target.rel} is a generated workflow for a different agent folder. ` +
+                `Agent slug '${target.slug}' is already in use; choose unique dharta.toml names before setup.`);
+        }
+        if (path.resolve(dest) !== path.resolve(target.dest) && deploysTarget) {
+            const rel = `.github/workflows/${entry.name}`;
+            throw new Error(`${rel} already deploys ${target.agentDir}. Remove or rename that generated workflow ` +
+                "before changing this agent's name, or both workflows could deploy the same folder.");
+        }
+    }
+}
+async function rejectLegacyRepoWorkflow(workflowsDir, targetDest) {
+    const rel = ".github/workflows/dharta-deploy.yml";
+    const dest = path.join(workflowsDir, "dharta-deploy.yml");
+    let content;
+    try {
+        content = await fs.readFile(dest, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT" ||
+            error.code === "EISDIR")
+            return;
+        throw error;
+    }
+    const generatedLegacy = content.includes("# Deploy this repo's Dharta agents on every push (RFC 0024).") &&
+        content.includes("DHARTA_API_KEY: ${{ secrets.DHARTA_API_KEY }}") &&
+        content.includes("run: dharta deploy --mode folder");
+    if (generatedLegacy) {
+        throw new Error(`${rel} is Dharta's legacy repo-wide deploy workflow and can duplicate or fan out deploys. ` +
+            `Remove it, then rerun setup to create one path-scoped workflow per agent. No files were changed.`);
+    }
+    if (!isManagedWorkflow(content) && path.resolve(dest) !== path.resolve(targetDest)) {
+        throw new Error(`${rel} already exists but is not a current per-agent Dharta workflow. ` +
+            "Inspect, remove, or rename it before enabling per-agent CI; setup left every file unchanged.");
+    }
+}
+async function existingWorkflowState(target, log) {
+    const { dest, rel } = target;
+    try {
+        const stat = await fs.lstat(dest);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Cannot write ${rel}: the workflow file is a symbolic link.`);
+        }
+        if (stat.isDirectory()) {
+            throw new Error(`Cannot write ${rel}: expected a file, got a directory.`);
+        }
+        const content = await fs.readFile(dest, "utf8");
+        if (isManagedWorkflow(content))
+            return "generated";
+        log(`CI: github requested, but ${rel} is a custom workflow. Left it unchanged; ` +
+            "CI was not configured. Verify and maintain that workflow yourself.");
+        return "custom";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "missing";
+        throw error;
+    }
+}
+function isManagedWorkflow(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0] === MANAGED_WORKFLOW_MARKER) {
+        return /^# Deploy only the [a-z0-9-]+ Dharta agent\.$/.test(lines[1] ?? "") &&
+            /^# Agent directory: ".*"\.$/.test(lines[2] ?? "");
+    }
+    // Compatibility for the per-agent workflow format emitted immediately
+    // before the explicit ownership marker existed. Its exact first two lines,
+    // pinned-method comment, and deploy command form a narrow signature; a
+    // custom workflow that merely mentions the old generator phrase is not
+    // adopted or overwritten.
+    return /^# Deploy only the [a-z0-9-]+ Dharta agent\. Generated by dharta setup\.$/.test(lines[0] ?? "") &&
+        /^# Agent directory: ".*"\.$/.test(lines[1] ?? "") &&
+        content.includes("# The command is pinned to the ") &&
+        /dharta deploy --mode (git|folder) --dir /.test(content);
+}
+// Validate an existing directory without following any repo-relative symlink.
+// We deliberately start at the setup/repo boundary instead of walking system
+// ancestors: platform paths such as /var may themselves be legitimate OS
+// links, while every component controlled by the working tree must be real.
+async function validateExistingDirectoryTree(root, target, label) {
+    const absoluteRoot = path.resolve(root);
+    const absoluteTarget = path.resolve(target);
+    const rootStat = await fs.lstat(absoluteRoot);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error(`${label}: '.' is a symbolic link. ` +
+            "Dharta setup does not follow links when selecting an agent folder.");
+    }
+    if (!rootStat.isDirectory())
+        throw new Error(`${label}: a parent path is not a directory.`);
+    // Check the caller-visible leaf before realpath so a selected agent symlink
+    // is rejected even when it resolves back inside the repo.
+    const targetLeaf = await fs.lstat(absoluteTarget);
+    if (targetLeaf.isSymbolicLink()) {
+        throw new Error(`${label}: '${path.basename(absoluteTarget)}' is a symbolic link. ` +
+            "Dharta setup does not follow links when selecting an agent folder.");
+    }
+    if (!targetLeaf.isDirectory())
+        throw new Error(`${label}: expected a directory, got a file.`);
+    const [rootReal, targetReal] = await Promise.all([fs.realpath(absoluteRoot), fs.realpath(absoluteTarget)]);
+    const realRelative = containedRelativePath(rootReal, targetReal);
+    if (realRelative === undefined) {
+        throw new Error(`${label}: the resolved path escapes the current setup root.`);
+    }
+    // Prefer the caller-visible path when it is lexically below the boundary so
+    // repo-controlled intermediate symlinks are observable. macOS commonly
+    // exposes the same safe temp directory through /var and /private/var; when
+    // those lexical aliases differ, walk the already-contained canonical path.
+    const lexicalRelative = containedRelativePath(absoluteRoot, absoluteTarget);
+    const walkRoot = lexicalRelative === undefined ? rootReal : absoluteRoot;
+    const relativeTarget = lexicalRelative ?? realRelative;
+    const components = relativeTarget === "" ? [] : relativeTarget.split(path.sep);
+    let current = walkRoot;
+    for (const component of components) {
+        current = path.join(current, component);
+        const stat = await fs.lstat(current);
+        const display = path.relative(walkRoot, current) || ".";
+        if (stat.isSymbolicLink()) {
+            throw new Error(`${label}: '${display}' is a symbolic link. ` +
+                "Dharta setup does not follow links when selecting an agent folder.");
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`${label}: a parent path is not a directory.`);
+        }
+    }
+}
+// Validate (and optionally create) every parent below a trusted root. lstat is
+// intentional: stat/readFile/writeFile would follow a final symlink. A realpath
+// containment check provides a second invariant for platforms with links in
+// unusual directory layouts.
+async function validateSafeWriteTarget(root, destination, label, createParents) {
+    const absoluteRoot = path.resolve(root);
+    const absoluteDestination = path.resolve(destination);
+    const relativeDestination = containedRelativePath(absoluteRoot, absoluteDestination);
+    if (relativeDestination === undefined || relativeDestination === "") {
+        throw new Error(`Cannot write ${label}: destination is outside its intended root.`);
+    }
+    await validateExistingDirectoryTree(absoluteRoot, absoluteRoot, `Cannot write ${label}`);
+    const rootReal = await fs.realpath(absoluteRoot);
+    const parent = path.dirname(absoluteDestination);
+    const relativeParent = path.relative(absoluteRoot, parent);
+    const components = relativeParent === "" ? [] : relativeParent.split(path.sep);
+    let current = absoluteRoot;
+    let parentMissing = false;
+    for (const component of components) {
+        current = path.join(current, component);
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            if (!createParents) {
+                parentMissing = true;
+                break;
+            }
+            try {
+                await fs.mkdir(current);
+            }
+            catch (mkdirError) {
+                if (mkdirError.code !== "EEXIST")
+                    throw mkdirError;
+            }
+            stat = await fs.lstat(current);
+        }
+        const display = path.relative(absoluteRoot, current) || ".";
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Cannot write ${label}: parent '${display}' is a symbolic link. ` +
+                "Dharta setup refuses to follow links for generated files.");
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`Cannot write ${label}: a parent path is not a directory.`);
+        }
+        const currentReal = await fs.realpath(current);
+        if (containedRelativePath(rootReal, currentReal) === undefined) {
+            throw new Error(`Cannot write ${label}: parent '${display}' resolves outside its intended root.`);
+        }
+    }
+    if (parentMissing)
+        return { rootReal };
+    let existing;
+    try {
+        existing = await fs.lstat(absoluteDestination);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return { rootReal };
+        if (code === "ENOTDIR") {
+            throw new Error(`Cannot write ${label}: a parent path is not a directory.`);
+        }
+        throw error;
+    }
+    if (existing.isSymbolicLink()) {
+        throw new Error(`Cannot write ${label}: the destination is a symbolic link. ` +
+            "Dharta setup refuses to follow links for generated files.");
+    }
+    if (existing.isDirectory())
+        throw new Error(`Cannot write ${label}: expected a file, got a directory.`);
+    if (!existing.isFile())
+        throw new Error(`Cannot write ${label}: expected a regular file.`);
+    const destinationReal = await fs.realpath(absoluteDestination);
+    if (containedRelativePath(rootReal, destinationReal) === undefined) {
+        throw new Error(`Cannot write ${label}: destination resolves outside its intended root.`);
+    }
+    return { rootReal, existing };
+}
+// Write through a fresh same-directory file and atomically replace the final
+// path. O_NOFOLLOW protects the temporary leaf; lstat rejects a linked final
+// leaf; rename replaces rather than dereferences a link introduced after the
+// check. This also avoids leaving half a manifest/workflow on interruption.
+async function safeAtomicWriteFile(root, destination, label, content) {
+    const prepared = await validateSafeWriteTarget(root, destination, label, true);
+    const parent = path.dirname(destination);
+    const temporary = path.join(parent, `.${path.basename(destination)}.karta-${process.pid}-${randomBytes(12).toString("hex")}.tmp`);
+    const noFollow = constants.O_NOFOLLOW ?? 0;
+    const flags = constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | noFollow;
+    const finalMode = prepared.existing ? prepared.existing.mode & 0o777 : 0o644;
+    let handle;
+    let renamed = false;
+    try {
+        handle = await fs.open(temporary, flags, 0o600);
+        const opened = await handle.stat();
+        const temporaryReal = await fs.realpath(temporary);
+        if (containedRelativePath(prepared.rootReal, temporaryReal) === undefined) {
+            throw new Error(`Cannot write ${label}: temporary file escaped its intended root.`);
+        }
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+        await handle.chmod(finalMode);
+        await handle.close();
+        handle = undefined;
+        // Re-check after writing, immediately before the atomic replacement. The
+        // inode comparison ensures the lexical temporary path still names the file
+        // descriptor we created rather than a swapped link/file.
+        await validateSafeWriteTarget(root, destination, label, true);
+        const tempStat = await fs.lstat(temporary);
+        if (!tempStat.isFile() || tempStat.isSymbolicLink() ||
+            tempStat.dev !== opened.dev || tempStat.ino !== opened.ino) {
+            throw new Error(`Cannot write ${label}: temporary file changed during setup.`);
+        }
+        const checkedTemporaryReal = await fs.realpath(temporary);
+        if (containedRelativePath(prepared.rootReal, checkedTemporaryReal) === undefined) {
+            throw new Error(`Cannot write ${label}: temporary file escaped its intended root.`);
+        }
+        await fs.rename(temporary, destination);
+        renamed = true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith(`Cannot write ${label}:`))
+            throw error;
+        throw new Error(`Cannot write ${label}: ${error.message}`);
+    }
+    finally {
+        await handle?.close().catch(() => { });
+        if (!renamed)
+            await fs.unlink(temporary).catch(() => { });
+    }
+}
+async function lstatIfPresent(file) {
+    try {
+        return await fs.lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function containedRelativePath(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    if (path.isAbsolute(relative) || relative === ".." || relative.startsWith(`..${path.sep}`)) {
+        return undefined;
+    }
+    return relative;
+}
+async function rejectGitignoredSetupFile(git, repoRoot, destination, label) {
+    const relative = containedRelativePath(repoRoot, destination);
+    if (relative === undefined || relative === "") {
+        throw new Error(`Cannot check ${label}: path is outside the git repo.`);
+    }
+    const gitPath = relative.split(path.sep).join("/");
+    // Do not pass --no-index: an already tracked generated file remains part of
+    // the repo even if a later ignore rule matches it. New/untracked generated
+    // files are the ones setup must reject as impossible to push.
+    const result = await git(["-C", repoRoot, "check-ignore", "-q", "--", gitPath]);
+    if (result.code === 1)
+        return;
+    if (result.code !== 0) {
+        throw new Error(`git could not check ignore rules for ${gitPath}: ${result.stderr.trim() || `exit ${result.code}`}`);
+    }
+    throw new Error(`Cannot configure ${label}: ${gitPath} is excluded by .gitignore. ` +
+        "Unignore it, then rerun setup; Dharta did not write the generated file or report it ready to push.");
+}
+function renderDeployWorkflow(target) {
+    const pushPaths = githubPushPaths(target);
+    const scope = target.method === "folder" ? "releases:write" : "source_repos:write";
+    const reconcileSource = target.method === "git" ? " --reconcile-source" : "";
+    const command = `dharta deploy --mode ${target.method}${reconcileSource} --dir ${shellQuote(target.agentDir)}`;
+    const concurrency = target.method === "git"
+        ? "dharta-git-deploy-${{ github.repository }}"
+        : `dharta-deploy-${target.slug}`;
+    return [
+        MANAGED_WORKFLOW_MARKER,
+        `# Deploy only the ${target.slug} Dharta agent.`,
+        `# Agent directory: ${JSON.stringify(target.agentDir)}.`,
+        "#",
+        `# Authentication comes from this agent's ${target.secretName} repo secret.`,
+        `# The command is pinned to the ${target.method} method used to render this workflow.`,
+        ...(target.method === "git" ? [
+            "# --reconcile-source is safe here only because the branch-tip guard below rejects stale runs.",
+        ] : []),
+        "# To change deploy_method, update dharta.toml by rerunning setup, regenerate this workflow,",
+        "# and rotate the secret so its operation scope matches the new method:",
+        `# rerun: dharta setup ${shellQuote(target.agentDir)} --ci github`,
+        "#",
+        "# Required repo secret:",
+        `#   ${target.secretName}   a dh_live_... key with \`${scope}\`:`,
+        `#                   dharta keys create ci-${target.slug} --scope ${scope}`,
+        "#                   (requires an active key with keys:write; dashboard creation also works)",
+        "# Optional repo variable:",
+        "#   DHARTA_BASE_URL  control-plane URL (defaults to https://dharta.ai).",
+        "",
+        `name: Deploy ${target.slug} to Dharta`,
+        "",
+        "on:",
+        "  push:",
+        `    branches: [${JSON.stringify(githubLiteralPath(target.branch))}]`,
+        "    paths:",
+        ...pushPaths.map((triggerPath) => `      - ${JSON.stringify(triggerPath)}`),
+        "  workflow_dispatch:",
+        "",
+        "permissions:",
+        "  contents: read",
+        "",
+        "concurrency:",
+        `  group: ${concurrency}`,
+        "  queue: max",
+        "  cancel-in-progress: false",
+        "",
+        "jobs:",
+        "  deploy:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        ...(target.method === "git" ? ["        with:", "          fetch-depth: 0"] : []),
+        "      - uses: actions/setup-node@v4",
+        '        with:',
+        '          node-version: "20"',
+        "      - name: Install Dharta CLI",
+        `        run: npm install --global @dharta/cli@${CLI_VERSION}`,
+        "      - name: Check current branch tip",
+        "        id: freshness",
+        "        env:",
+        `          DHARTA_DEPLOY_BRANCH: ${JSON.stringify(target.branch)}`,
+        "        run: |",
+        "          git fetch --no-tags --force origin \"refs/heads/${DHARTA_DEPLOY_BRANCH}:refs/remotes/origin/dharta-deploy-tip\"",
+        "          tip=\"$(git rev-parse refs/remotes/origin/dharta-deploy-tip)\"",
+        "          if [ \"$GITHUB_SHA\" = \"$tip\" ]; then",
+        "            echo \"deploy=true\" >> \"$GITHUB_OUTPUT\"",
+        "          else",
+        `            echo "Skipping stale ${target.method} deploy: workflow SHA $GITHUB_SHA is not current branch tip $tip."`,
+        "            echo \"deploy=false\" >> \"$GITHUB_OUTPUT\"",
+        "          fi",
+        "      - name: Deploy",
+        "        if: steps.freshness.outputs.deploy == 'true'",
+        "        env:",
+        `          DHARTA_API_KEY: \${{ secrets.${target.secretName} }}`,
+        "          DHARTA_BASE_URL: ${{ vars.DHARTA_BASE_URL || 'https://dharta.ai' }}",
+        `        run: ${JSON.stringify(command)}`,
+        "",
+    ].join("\n");
+}
+function githubPushPaths(target) {
+    // A root agent's `**` covers its own .gitignore and generated workflow.
+    if (target.agentDir === ".")
+        return ["**"];
+    const paths = new Set([`${githubLiteralPath(target.agentDir)}/**`]);
+    const parts = target.agentDir.split("/");
+    // Folder packaging applies ignore rules from the checkout root through the
+    // selected folder. Include every *potential* ancestor .gitignore, even when
+    // it does not exist yet, so adding one cannot silently change the package
+    // without triggering CI. The selected folder's own .gitignore is already
+    // covered by the subtree glob, hence the strict `< parts.length` bound.
+    for (let depth = 0; depth < parts.length; depth += 1) {
+        const prefix = parts.slice(0, depth).join("/");
+        const ignorePath = prefix ? `${prefix}/.gitignore` : ".gitignore";
+        paths.add(githubLiteralPath(ignorePath));
+    }
+    // Ordinarily a generated-workflow edit should trigger its deploy. Avoid a
+    // duplicate when an unusually placed agent subtree already covers it.
+    if (!target.rel.startsWith(`${target.agentDir}/`)) {
+        paths.add(githubLiteralPath(target.rel));
+    }
+    return [...paths];
+}
+function githubLiteralPath(value) {
+    // GitHub `paths` values are glob patterns even when YAML-quoted. Escape
+    // metacharacters that are legal in git directory names so a literal agent
+    // path cannot broaden, negate, or otherwise change its workflow trigger.
+    return value.replace(/[\\*?+!\[\]]/g, "\\$&");
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function relLabel(dir) {
+    const rel = path.relative(process.cwd(), dir);
+    return rel === "" ? "./" : `./${rel}`;
+}
+// (ensureRemote lives on the deploy command; setup stays destination-
+// agnostic and lets `dharta deploy` provision + wire the remote.)
+function yesNo(answer, fallback) {
+    const a = answer.trim().toLowerCase();
+    if (a === "")
+        return fallback;
+    return a === "y" || a === "yes";
+}
+function yesNoCancel(answer) {
+    const a = answer.trim().toLowerCase();
+    if (a === "n" || a === "no")
+        return "no";
+    if (a === "c" || a === "cancel")
+        return "cancel";
+    return "yes"; // empty (the [Yes] default) or y/yes
+}
+async function run(git, args, label) {
+    const r = await git(args);
+    if (r.code !== 0)
+        throw new Error(`${label} failed: ${r.stderr.trim() || `exit ${r.code}`}`);
+}
+//# sourceMappingURL=setup.js.map