airdy 0.1.0

package/dist/main.js

@@ -0,0 +1,312 @@
+import { basename, join } from "node:path";
+import { readdir, readFile, lstat, readlink } from "node:fs/promises";
+import { spawn as nodeSpawn } from "node:child_process";
+import { parseArgs } from "./cli/args.js";
+import { getVersion } from "./version.js";
+import { detectContext, checkPreflight } from "./context.js";
+import { loadUserConfig, mergePackages, loadAnswersFromConfig, } from "./config/user.js";
+import { readState, answersFromState, stateAction, } from "./state/agentsetup.js";
+import { buildPlan, describePlan } from "./plan/builder.js";
+import { executePlan } from "./plan/executor.js";
+import { resolveConflict, resolveLinkConflict, previewAction, applyChoice, unifiedDiff, } from "./plan/conflicts.js";
+import { promptConflict, promptOverwritePath } from "./prompts/conflict.js";
+import { preGit, postGit } from "./git/steps.js";
+import { getAdapter } from "./adapters/index.js";
+import { loadModule } from "./workflows/module.js";
+import { runWizard, confirmPlan } from "./prompts/wizard.js";
+async function loadPresetModules(sources) {
+    const modules = {};
+    for (const src of sources) {
+        let entries;
+        try {
+            entries = await readdir(src);
+        }
+        catch {
+            continue; // preset source dir missing; skip
+        }
+        for (const entry of entries) {
+            try {
+                const mod = await loadModule(join(src, entry));
+                modules[mod.name] = mod;
+            }
+            catch {
+                // not a module dir (no module.json); ignore
+            }
+        }
+    }
+    return modules;
+}
+function isEnoent(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+// Only a genuinely absent file counts as "no conflict". Any other read error
+// (permission denied, a directory in the file's place) must surface, not be
+// silently treated as absent — otherwise the conflict layer would let a write
+// proceed against a file it could not actually read.
+async function readIfExists(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return null;
+        throw err;
+    }
+}
+// Only a genuinely absent destination counts as "no conflict" here too (see
+// readIfExists above): any other lstat error (permission denied, etc.) must
+// propagate rather than be silently treated as absent.
+async function probeLink(abs) {
+    let st;
+    try {
+        st = await lstat(abs);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return { exists: false, currentLink: null };
+        throw err;
+    }
+    let currentLink = null;
+    if (st.isSymbolicLink()) {
+        try {
+            currentLink = await readlink(abs);
+        }
+        catch {
+            currentLink = null;
+        }
+    }
+    return { exists: true, currentLink };
+}
+export async function resolvePlanConflicts(plan, root, ownedPaths, interactive) {
+    const owned = new Set(ownedPaths);
+    const finalPlan = [];
+    const conflictSkipped = [];
+    for (const action of plan) {
+        if (action.type === "write-file") {
+            const existing = await readIfExists(join(root, action.path));
+            if (resolveConflict(action, existing, owned) === "proceed") {
+                finalPlan.push(action);
+                continue;
+            }
+            if (!interactive) {
+                // --yes default: skip existing non-airdy files, report them
+                conflictSkipped.push(action.path);
+                continue;
+            }
+            const diff = unifiedDiff(existing ?? "", previewAction(action, existing ?? ""), action.path);
+            const choice = await promptConflict(action.path, diff);
+            const resolved = applyChoice(action, choice, existing ?? "");
+            if (resolved)
+                finalPlan.push(resolved);
+            else
+                conflictSkipped.push(action.path);
+            continue;
+        }
+        if (action.type === "symlink" || action.type === "copy-dir") {
+            const dest = action.type === "symlink" ? action.path : action.to;
+            const desired = action.type === "symlink" ? action.target : null;
+            const probe = await probeLink(join(root, dest));
+            if (resolveLinkConflict(dest, desired, probe, owned) === "proceed") {
+                finalPlan.push(action);
+                continue;
+            }
+            if (!interactive) {
+                conflictSkipped.push(dest);
+                continue;
+            }
+            const overwrite = await promptOverwritePath(dest);
+            if (overwrite)
+                finalPlan.push(action);
+            else
+                conflictSkipped.push(dest);
+            continue;
+        }
+        // merge-markdown / merge-json: additive per marker/key and idempotent
+        finalPlan.push(action);
+    }
+    return { finalPlan, conflictSkipped };
+}
+// The executor's applied/skipped entries are labels; map an action back to the
+// project-relative destination path it actually writes.
+function actionLabel(a) {
+    return "path" in a ? a.path : `${a.from} -> ${a.to}`;
+}
+function actionDest(a) {
+    return a.type === "copy-dir" ? a.to : a.path;
+}
+// Only actions that wholly create/replace their destination confer ownership;
+// merge-markdown/merge-json only merge into a path that may pre-exist as a
+// user file, so an applied merge must never mark its target airdy-owned.
+function isAuthoringAction(action) {
+    return (action.type === "write-file" ||
+        action.type === "symlink" ||
+        action.type === "copy-dir");
+}
+// Union of prior ownedPaths with the destinations actually authored this run.
+function nextOwnedPaths(prior, finalPlan, report) {
+    const applied = new Set(report.applied);
+    const owned = new Set(prior);
+    for (const action of finalPlan) {
+        if (!isAuthoringAction(action))
+            continue;
+        if (applied.has(actionLabel(action)))
+            owned.add(actionDest(action));
+    }
+    return [...owned].sort();
+}
+export async function launchOrPrint(launchAgent, ctx, cwd, opts) {
+    const adapter = getAdapter(launchAgent);
+    if (adapter.trustNote)
+        console.log(`\nNote: ${adapter.trustNote}`);
+    const { cmd, args } = adapter.launchCommand(ctx);
+    const full = [cmd, ...args].join(" ");
+    // print-only path (dry-run, non-interactive, or --yes): never spawn
+    if (!opts.interactive) {
+        console.log(`\nTo start ${launchAgent}: ${full}`);
+        return 0;
+    }
+    // guard: if the launch agent's CLI is not installed, print the command with a
+    // note instead of spawning a process that would immediately fail (consistent
+    // with checkPreflight's warning).
+    const cliKey = adapter.cliName;
+    const cliAvailable = ctx.cli?.[cliKey] ?? false;
+    if (!cliAvailable) {
+        console.log(`\nTo start ${launchAgent}: ${full}`);
+        console.log(`(${cmd} CLI not found on PATH — install it, then run the command above)`);
+        return 0;
+    }
+    console.log(`\nLaunching ${launchAgent}...`);
+    return await new Promise((resolve) => {
+        const child = opts.spawn(cmd, args, { cwd, stdio: "inherit" });
+        child.on("error", (err) => {
+            console.error(`could not launch ${cmd}: ${err.message}`);
+            resolve(1);
+        });
+        child.on("exit", (code) => resolve(code ?? 0));
+    });
+}
+const HELP = `airdy — project setup wizard for coding agents
+
+Usage: airdy [options]
+
+Options:
+  -y, --yes            non-interactive; requires --config
+      --config <file>  answers JSON for non-interactive mode
+      --dry-run        print the plan without writing
+      --copy           copy skills into .claude/skills instead of symlinking
+  -v, --version        print version
+  -h, --help           print this help`;
+export async function main(argv, cwd, deps = {}) {
+    const args = parseArgs(argv);
+    if (args.version) {
+        console.log(getVersion());
+        return 0;
+    }
+    if (args.help) {
+        console.log(HELP);
+        return 0;
+    }
+    // shared interactivity predicate: conflict prompting and launch both use it
+    // (non-TTY without --yes must never open a clack prompt)
+    const interactive = !args.yes && (deps.isTTY ?? process.stdout.isTTY === true);
+    const spawnFn = deps.spawn ?? ((cmd, cmdArgs, opts) => nodeSpawn(cmd, cmdArgs, opts));
+    const ctx = await detectContext(cwd);
+    const userConfig = await loadUserConfig(deps.home);
+    const packages = mergePackages(userConfig);
+    const state = await readState(cwd);
+    const ownedPaths = state?.ownedPaths ?? [];
+    let answers;
+    if (args.yes) {
+        if (!args.configPath) {
+            console.error("--yes requires --config <file>");
+            return 1;
+        }
+        answers = await loadAnswersFromConfig(args.configPath, cwd, args.copy);
+    }
+    else {
+        const prefill = state ? answersFromState(state) : {};
+        const result = await runWizard(ctx, userConfig, prefill);
+        if (!result) {
+            console.log("Cancelled.");
+            return 1;
+        }
+        answers = result;
+    }
+    for (const w of checkPreflight(answers, ctx))
+        console.warn(`! ${w}`);
+    const modules = await loadPresetModules(userConfig.presetSources);
+    const plan = await buildPlan(answers, ctx, {
+        projectName: basename(cwd),
+        packages,
+        modules,
+        ownedPaths,
+    });
+    console.log("\nPlanned changes:");
+    console.log(describePlan(plan));
+    if (args.dryRun) {
+        console.log("\n(dry run — nothing written)");
+        if (answers.launchAgent) {
+            // print-only path: never spawn under --dry-run
+            await launchOrPrint(answers.launchAgent, ctx, cwd, {
+                interactive: false,
+                spawn: spawnFn,
+            });
+        }
+        return 0;
+    }
+    if (!args.yes) {
+        const ok = await confirmPlan();
+        if (!ok) {
+            console.log("Aborted.");
+            return 1;
+        }
+    }
+    // three-way conflict resolution driven by per-path provenance (ownedPaths)
+    const { finalPlan, conflictSkipped } = await resolvePlanConflicts(plan, cwd, ownedPaths, interactive);
+    if (conflictSkipped.length > 0) {
+        console.log(`Skipped (existing files not created by airdy): ${conflictSkipped.join(", ")}`);
+    }
+    if (ctx.cli.git && answers.git.kind !== "skip") {
+        try {
+            await preGit(answers.git, cwd);
+        }
+        catch (err) {
+            console.warn(`! git step failed: ${err.message}`);
+        }
+    }
+    const report = await executePlan(finalPlan, cwd);
+    // Persist provenance: union prior ownedPaths with the destinations actually
+    // written this run (even on a partial/failed run, so a re-run recognises them).
+    const newOwned = nextOwnedPaths(ownedPaths, finalPlan, report);
+    const stateReport = await executePlan([stateAction(answers, newOwned)], cwd);
+    if (stateReport.failed) {
+        // Ownership loss is safe-direction (a re-run may just re-prompt for
+        // already-answered settings), so warn instead of failing the run.
+        console.warn(`! failed to persist ownership state: ${stateReport.failed.error} (re-run may re-prompt)`);
+    }
+    if (report.failed) {
+        console.error(`\nStopped: ${report.failed.error}`);
+        console.error(`Applied ${report.applied.length}; the rest were not applied. Re-run to continue.`);
+        return 1;
+    }
+    console.log(`\nDone. ${report.applied.length} written, ${report.skipped.length} unchanged.`);
+    if (answers.git.kind === "gh-create" && ctx.cli.gh) {
+        try {
+            await postGit(answers.git, cwd);
+        }
+        catch (err) {
+            console.warn(`! gh repo create failed: ${err.message}`);
+        }
+    }
+    if (answers.launchAgent) {
+        // spawn only when interactive AND the user did not choose print-only
+        const wantSpawn = interactive && (answers.autoLaunch ?? true);
+        return await launchOrPrint(answers.launchAgent, ctx, cwd, {
+            interactive: wantSpawn,
+            spawn: spawnFn,
+        });
+    }
+    return 0;
+}

package/dist/merge/json.js

@@ -0,0 +1,33 @@
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export function deepMergeJson(base, patch) {
+    if (Array.isArray(base) && Array.isArray(patch)) {
+        const out = [...base];
+        for (const item of patch) {
+            const isPrimitive = item === null || typeof item !== "object";
+            if (isPrimitive) {
+                if (out.includes(item))
+                    continue;
+            }
+            else {
+                // structural equality via JSON.stringify; key-order sensitive, but
+                // same-source patches (e.g. re-running the same merge) are byte-identical
+                const serialized = JSON.stringify(item);
+                if (out.some((existing) => JSON.stringify(existing) === serialized))
+                    continue;
+            }
+            out.push(item);
+        }
+        return out;
+    }
+    if (isPlainObject(base) && isPlainObject(patch)) {
+        const out = { ...base };
+        for (const key of Object.keys(patch)) {
+            out[key] =
+                key in base ? deepMergeJson(base[key], patch[key]) : patch[key];
+        }
+        return out;
+    }
+    return patch;
+}

package/dist/merge/markdown.js

@@ -0,0 +1,16 @@
+export function mergeMarkdown(existing, marker, section) {
+    const start = `<!-- ${marker}:start -->`;
+    const end = `<!-- ${marker}:end -->`;
+    const block = `${start}\n${section}\n${end}`;
+    const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
+    if (pattern.test(existing)) {
+        return existing.replace(pattern, block);
+    }
+    const prefix = existing.length === 0 || existing.endsWith("\n")
+        ? existing
+        : existing + "\n";
+    return `${prefix}${existing.length === 0 ? "" : "\n"}${block}\n`;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/merge/template.js

@@ -0,0 +1,3 @@
+export function renderTemplate(tpl, vars) {
+    return tpl.replace(/\{\{(\w+)\}\}/g, (_m, key) => vars[key] ?? "");
+}

package/dist/plan/builder.js

@@ -0,0 +1,82 @@
+import { sep } from "node:path";
+import { renderProfile } from "../profiles/index.js";
+import { getAdapter } from "../adapters/index.js";
+import { builtinSuperpowersActions, moduleToActions, } from "../workflows/module.js";
+import { resolveSkillRefs, skillRefToActions } from "../skills/package.js";
+import { stateAction } from "../state/agentsetup.js";
+function targetPath(a) {
+    if ("path" in a)
+        return a.path;
+    if ("to" in a)
+        return a.to;
+    return "";
+}
+function targetsClaudeDir(a) {
+    const p = targetPath(a);
+    return (p === ".claude" || p.startsWith(".claude/") || p.startsWith(".claude" + sep));
+}
+export async function buildPlan(answers, ctx, deps) {
+    const actions = [];
+    // 1. project profile
+    const profile = renderProfile(answers.projectType, {
+        projectName: deps.projectName,
+    });
+    actions.push({
+        type: "write-file",
+        path: "AGENTS.md",
+        mode: "create",
+        contents: profile.agentsMd,
+    });
+    if (answers.git.kind === "init" || answers.git.kind === "gh-create") {
+        actions.push({
+            type: "write-file",
+            path: ".gitignore",
+            mode: "create",
+            contents: profile.gitignore,
+        });
+    }
+    // 2. workflows
+    for (const wf of answers.workflows) {
+        if (wf === "none")
+            continue;
+        if (wf === "superpowers") {
+            actions.push(...builtinSuperpowersActions());
+            continue;
+        }
+        const mod = deps.modules[wf];
+        if (mod)
+            actions.push(...(await moduleToActions(mod)));
+    }
+    // 3. skills -> .agents/skills (must precede the claude-code .claude/skills link)
+    const refs = resolveSkillRefs(answers.skillPackages, deps.packages, answers.extraSkills);
+    for (const ref of refs) {
+        actions.push(...(await skillRefToActions(ref)));
+    }
+    // 4. adapters
+    for (const id of answers.agents) {
+        actions.push(...getAdapter(id).contribute(answers, ctx));
+    }
+    // 5. state file
+    actions.push(stateAction(answers, deps.ownedPaths));
+    // gate: only claude-code owns .claude/*
+    const hasClaude = answers.agents.includes("claude-code");
+    return hasClaude ? actions : actions.filter((a) => !targetsClaudeDir(a));
+}
+export function describePlan(actions) {
+    return actions
+        .map((a) => {
+        switch (a.type) {
+            case "write-file":
+                return `  write    ${a.path} (${a.mode})`;
+            case "merge-markdown":
+                return `  merge    ${a.path} [${a.marker}]`;
+            case "merge-json":
+                return `  merge    ${a.path}`;
+            case "symlink":
+                return `  symlink  ${a.path} -> ${a.target}`;
+            case "copy-dir":
+                return `  copy     ${a.from} -> ${a.to}`;
+        }
+    })
+        .join("\n");
+}

package/dist/plan/conflicts.js

@@ -0,0 +1,113 @@
+import { mergeMarkdown } from "../merge/markdown.js";
+import { deepMergeJson } from "../merge/json.js";
+const AIRDY_OWNED_FILES = new Set(["agentsetup.json"]);
+// Ownership is per-path: a path airdy actually wrote in a prior run (recorded in
+// agentsetup.json's ownedPaths) plus airdy's own state file. A blanket "state
+// exists -> overwrite anything" rule silently clobbers files the user chose to
+// keep, so it is gone.
+export function isAirdyOwned(path, owned) {
+    return AIRDY_OWNED_FILES.has(path) || owned.has(path);
+}
+export function resolveConflict(action, existing, owned) {
+    // merge-* are additive per key/marker; symlink/copy-dir go through
+    // resolveLinkConflict which needs filesystem probes.
+    if (action.type !== "write-file")
+        return "proceed";
+    if (existing === null)
+        return "proceed";
+    if (isAirdyOwned(action.path, owned))
+        return "proceed";
+    return "needs-user";
+}
+// symlink / copy-dir destinations: a pre-existing, non-airdy path at the
+// destination is a conflict on the FIRST run. An already-correct symlink or an
+// airdy-owned path proceeds (idempotent re-run).
+export function resolveLinkConflict(dest, desiredLink, // symlink target; null for copy-dir
+probe, owned) {
+    if (!probe.exists)
+        return "proceed";
+    if (isAirdyOwned(dest, owned))
+        return "proceed";
+    if (desiredLink !== null && probe.currentLink === desiredLink)
+        return "proceed";
+    return "needs-user";
+}
+export function previewAction(action, existing) {
+    switch (action.type) {
+        case "write-file":
+            return action.contents;
+        case "merge-markdown":
+            return mergeMarkdown(existing, action.marker, action.section);
+        case "merge-json": {
+            let base = {};
+            try {
+                base = JSON.parse(existing);
+            }
+            catch {
+                base = {};
+            }
+            return JSON.stringify(deepMergeJson(base, action.patch), null, 2) + "\n";
+        }
+        default:
+            return existing;
+    }
+}
+export function applyChoice(action, choice, existing) {
+    if (choice === "skip")
+        return null;
+    if (action.type !== "write-file")
+        return action;
+    if (choice === "overwrite")
+        return { ...action, mode: "overwrite" };
+    // merge: append the planned contents after the existing ones
+    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+    return {
+        type: "write-file",
+        path: action.path,
+        mode: "overwrite",
+        contents: existing + sep + action.contents,
+    };
+}
+export function unifiedDiff(oldText, newText, path) {
+    const a = oldText.split("\n");
+    const b = newText.split("\n");
+    const m = a.length;
+    const n = b.length;
+    // LCS length table (small files only: config/docs, not source trees)
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i--) {
+        for (let j = n - 1; j >= 0; j--) {
+            lcs[i][j] =
+                a[i] === b[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const lines = [`--- ${path} (existing)`, `+++ ${path} (planned)`];
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (a[i] === b[j]) {
+            lines.push(`  ${a[i]}`);
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            lines.push(`- ${a[i]}`);
+            i++;
+        }
+        else {
+            lines.push(`+ ${b[j]}`);
+            j++;
+        }
+    }
+    while (i < m) {
+        lines.push(`- ${a[i]}`);
+        i++;
+    }
+    while (j < n) {
+        lines.push(`+ ${b[j]}`);
+        j++;
+    }
+    return lines.join("\n");
+}