airdy 0.1.0

package/dist/plan/executor.js

@@ -0,0 +1,183 @@
+import { mkdir, readFile, writeFile, symlink, cp, lstat, unlink, readlink, realpath, } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { mergeMarkdown } from "../merge/markdown.js";
+import { deepMergeJson } from "../merge/json.js";
+function label(action) {
+    if ("path" in action)
+        return action.path;
+    return `${action.from} -> ${action.to}`;
+}
+async function pathExists(p) {
+    try {
+        await lstat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Every write DESTINATION must stay inside the target project directory.
+// Resolves `relPath` against `root` and throws if it escapes lexically.
+function resolveContained(root, relPath) {
+    const resolvedRoot = resolve(root);
+    const abs = resolve(resolvedRoot, relPath);
+    if (abs !== resolvedRoot && !abs.startsWith(resolvedRoot + sep)) {
+        throw new Error(`refusing to write outside the project root: "${relPath}" resolves to "${abs}", which is not inside "${resolvedRoot}"`);
+    }
+    return abs;
+}
+// Lexical containment is not enough: a symlinked ancestor (e.g. `.claude` -> a
+// global config dir) can redirect writes outside the project. Resolve the
+// destination's deepest EXISTING ancestor via realpath and require it to be
+// inside realpath(root), so writes can never land outside the project tree.
+async function assertRealpathContained(realRoot, abs) {
+    let dir = dirname(abs);
+    while (!(await pathExists(dir))) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const realDir = await realpath(dir);
+    if (realDir !== realRoot && !realDir.startsWith(realRoot + sep)) {
+        throw new Error(`refusing to write outside the project root via a symlinked ancestor: "${abs}" resolves under "${realDir}", which is not inside "${realRoot}"`);
+    }
+}
+// The ancestor check above only covers the deepest EXISTING ancestor: if the
+// destination itself already exists as a symlink (e.g. a cloned repo ships
+// `.claude/settings.json -> ~/.claude/settings.json`), writes that go through
+// `readFile`/`writeFile` on that path follow the link. Require the final path,
+// if it is itself a symlink, to also realpath inside realRoot. Actions that
+// replace the link itself (`symlink`) don't write through it and opt out.
+async function assertFinalPathContained(realRoot, abs) {
+    let st;
+    try {
+        st = await lstat(abs);
+    }
+    catch {
+        return; // destination doesn't exist yet; nothing to follow
+    }
+    if (!st.isSymbolicLink())
+        return;
+    const real = await realpath(abs);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new Error(`refusing to write outside the project root via a symlinked destination: "${abs}" resolves to "${real}", which is not inside "${realRoot}"`);
+    }
+}
+async function containedDest(root, realRoot, relPath, opts = {}) {
+    const abs = resolveContained(root, relPath);
+    await assertRealpathContained(realRoot, abs);
+    if (opts.checkFinalPath !== false) {
+        await assertFinalPathContained(realRoot, abs);
+    }
+    return abs;
+}
+function isEnoent(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}
+async function applyAction(action, root, realRoot) {
+    switch (action.type) {
+        case "write-file": {
+            const abs = await containedDest(root, realRoot, action.path);
+            await mkdir(dirname(abs), { recursive: true });
+            if (action.mode === "create" && (await pathExists(abs)))
+                return "skipped";
+            await writeFile(abs, action.contents);
+            return "applied";
+        }
+        case "merge-markdown": {
+            const abs = await containedDest(root, realRoot, action.path);
+            await mkdir(dirname(abs), { recursive: true });
+            let existing = "";
+            try {
+                existing = await readFile(abs, "utf8");
+            }
+            catch (err) {
+                if (!isEnoent(err))
+                    throw err;
+                existing = "";
+            }
+            const merged = mergeMarkdown(existing, action.marker, action.section);
+            if (merged === existing)
+                return "skipped";
+            await writeFile(abs, merged);
+            return "applied";
+        }
+        case "merge-json": {
+            const abs = await containedDest(root, realRoot, action.path);
+            await mkdir(dirname(abs), { recursive: true });
+            let existingText = null;
+            try {
+                existingText = await readFile(abs, "utf8");
+            }
+            catch (err) {
+                if (!isEnoent(err))
+                    throw err;
+            }
+            // JSON.parse errors on an existing (corrupt) file are intentionally
+            // NOT caught here: they must propagate to the fail-stop report rather
+            // than silently clobber the file with a fresh merge.
+            const base = existingText === null ? {} : JSON.parse(existingText);
+            const merged = deepMergeJson(base, action.patch);
+            if (existingText !== null &&
+                JSON.stringify(merged) === JSON.stringify(base)) {
+                return "skipped";
+            }
+            await writeFile(abs, JSON.stringify(merged, null, 2) + "\n");
+            return "applied";
+        }
+        case "symlink": {
+            const abs = await containedDest(root, realRoot, action.path, {
+                checkFinalPath: false,
+            });
+            await mkdir(dirname(abs), { recursive: true });
+            if (await pathExists(abs)) {
+                try {
+                    if ((await readlink(abs)) === action.target)
+                        return "skipped";
+                }
+                catch {
+                    // not a symlink; fall through to replace
+                }
+                await unlink(abs);
+            }
+            await symlink(action.target, abs);
+            return "applied";
+        }
+        case "copy-dir": {
+            const absFrom = isAbsolute(action.from)
+                ? action.from
+                : join(root, action.from);
+            const absTo = await containedDest(root, realRoot, action.to);
+            await mkdir(dirname(absTo), { recursive: true });
+            // Always reported "applied": comparing directory trees for idempotency
+            // isn't worth the complexity at MVP scale.
+            await cp(absFrom, absTo, { recursive: true });
+            return "applied";
+        }
+    }
+}
+export async function executePlan(actions, root) {
+    const report = { applied: [], skipped: [], failed: null };
+    // realpath the project root once; every write is checked against it.
+    const realRoot = await realpath(resolve(root));
+    for (const action of actions) {
+        try {
+            const result = await applyAction(action, root, realRoot);
+            if (result === "applied")
+                report.applied.push(label(action));
+            else
+                report.skipped.push(label(action));
+        }
+        catch (err) {
+            report.failed = {
+                action,
+                error: err instanceof Error ? err.message : String(err),
+            };
+            return report;
+        }
+    }
+    return report;
+}

package/dist/profiles/index.js

@@ -0,0 +1,15 @@
+import { renderTemplate } from "../merge/template.js";
+import { AGENTS_SKELETON, PROFILES } from "./templates.js";
+export function renderProfile(type, vars) {
+    const def = PROFILES[type];
+    const agentsMd = renderTemplate(AGENTS_SKELETON, {
+        projectName: vars.projectName,
+        typeLabel: def.typeLabel,
+        stackNotes: def.stackNotes,
+    });
+    return {
+        agentsMd,
+        gitignore: def.gitignore,
+        suggestedPackages: def.suggestedPackages,
+    };
+}

package/dist/profiles/templates.js

@@ -0,0 +1,68 @@
+export const AGENTS_SKELETON = `# {{projectName}}
+
+> Canonical agent instructions for this project. CLAUDE.md is only a pointer — edit **this** file.
+
+## Project Type
+
+{{typeLabel}}
+
+## Stack & Conventions
+
+{{stackNotes}}
+
+## Workflows
+`;
+const GITIGNORE_BASE = `node_modules/
+dist/
+build/
+.env
+.env.*
+*.log
+.DS_Store
+
+# airdy: keep agent config in version control, ignore only local overrides
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+!.claude/scripts/
+!.claude/skills
+.claude/settings.local.json
+`;
+export const PROFILES = {
+    web: {
+        typeLabel: "Web frontend / full-stack application.",
+        stackNotes: "- Prefer the framework's official conventions.\n- Keep components small and typed.",
+        suggestedPackages: ["web"],
+        gitignore: GITIGNORE_BASE + "\n.next/\n.vite/\ncoverage/\n",
+    },
+    "mobile-app": {
+        typeLabel: "Mobile application.",
+        stackNotes: "- Follow platform HIG / Material guidelines.\n- Keep view state explicit.",
+        suggestedPackages: ["mobile"],
+        gitignore: GITIGNORE_BASE + "\nDerivedData/\n*.xcuserstate\n",
+    },
+    backend: {
+        typeLabel: "Backend service / API.",
+        stackNotes: "- Layer domain logic away from transport.\n- Validate all external input.",
+        suggestedPackages: ["backend"],
+        gitignore: GITIGNORE_BASE + "\ncoverage/\n*.pid\n",
+    },
+    desktop: {
+        typeLabel: "Desktop application.",
+        stackNotes: "- Keep platform-specific code isolated.",
+        suggestedPackages: ["desktop"],
+        gitignore: GITIGNORE_BASE + "\nout/\n",
+    },
+    "oss-fork": {
+        typeLabel: "Fork of an upstream open-source project.",
+        stackNotes: "- Preserve upstream conventions.\n- Keep local changes minimal and well-documented.",
+        suggestedPackages: [],
+        gitignore: GITIGNORE_BASE,
+    },
+    minimal: {
+        typeLabel: "Minimal / unspecified.",
+        stackNotes: "- No assumptions; the launched agent will establish conventions.",
+        suggestedPackages: [],
+        gitignore: GITIGNORE_BASE,
+    },
+};

package/dist/prompts/conflict.js

@@ -0,0 +1,39 @@
+import { select, isCancel } from "@clack/prompts";
+export async function promptConflict(path, diff) {
+    console.log(`\n${path} already exists and was not created by airdy. Planned change:\n`);
+    console.log(diff);
+    const choice = await select({
+        message: `How should ${path} be handled?`,
+        options: [
+            { value: "skip", label: "skip — keep the existing file" },
+            {
+                value: "overwrite",
+                label: "overwrite — replace with the planned content",
+            },
+            { value: "merge", label: "merge — append the planned content" },
+        ],
+        initialValue: "skip",
+    });
+    if (isCancel(choice))
+        return "skip";
+    return choice;
+}
+// symlink / copy-dir destinations have no text diff to merge — a plain
+// keep-or-replace decision. Returns true to overwrite, false to skip.
+export async function promptOverwritePath(path) {
+    console.log(`\n${path} already exists and was not created by airdy.`);
+    const choice = await select({
+        message: `How should ${path} be handled?`,
+        options: [
+            { value: "skip", label: "skip — keep the existing path" },
+            {
+                value: "overwrite",
+                label: "overwrite — replace it with airdy's version",
+            },
+        ],
+        initialValue: "skip",
+    });
+    if (isCancel(choice))
+        return false;
+    return choice === "overwrite";
+}

package/dist/prompts/wizard.js

@@ -0,0 +1,217 @@
+import { intro, outro, select, multiselect, confirm, text, isCancel, cancel, } from "@clack/prompts";
+import { basename } from "node:path";
+import { allAdapters } from "../adapters/index.js";
+import { mergePackages } from "../config/user.js";
+import { PROFILES } from "../profiles/templates.js";
+const PROJECT_TYPES = [
+    { value: "web", label: "Web frontend / full-stack" },
+    { value: "mobile-app", label: "Mobile app" },
+    { value: "backend", label: "Backend service / API" },
+    { value: "desktop", label: "Desktop app" },
+    { value: "oss-fork", label: "Open-source fork" },
+    { value: "minimal", label: "Minimal / unspecified" },
+];
+const WORKFLOWS = [
+    {
+        value: "superpowers",
+        label: "superpowers",
+        hint: "brainstorm -> plan -> TDD -> review",
+    },
+    { value: "verify-loop", label: "verify-loop", hint: "needs a preset source" },
+    { value: "ship-gate", label: "ship-gate", hint: "needs a preset source" },
+    { value: "none", label: "none" },
+];
+// Initial skill-package selection: a re-run restores the prior choice; a fresh
+// run pre-selects the project type's suggested packages, filtered to the ones
+// actually offered (per spec: project type pre-selects packages).
+export function initialSkillPackages(prefill, projectType, offered) {
+    if (prefill.skillPackages)
+        return prefill.skillPackages;
+    const suggested = PROFILES[projectType]?.suggestedPackages ?? [];
+    return suggested.filter((name) => name in offered);
+}
+export function parseExtraSkillUrls(input) {
+    return input
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((token) => {
+        const clean = token.replace(/^https?:\/\//, "").replace(/\.git$/, "");
+        const parts = clean.split("/");
+        const repo = parts.slice(0, 3).join("/");
+        const subdir = parts.length > 3 ? parts.slice(3).join("/") : undefined;
+        return { source: "git", repo, subdir };
+    });
+}
+async function promptGit(ctx, prefill) {
+    const kind = await select({
+        message: "Git setup?",
+        options: [
+            { value: "init", label: "git init (branch main)" },
+            { value: "clone", label: "git clone a URL" },
+            { value: "gh-create", label: "gh repo create" },
+            { value: "skip", label: "skip" },
+        ],
+        initialValue: prefill.git?.kind ?? (ctx.isGitRepo ? "skip" : "init"),
+    });
+    if (isCancel(kind))
+        return null;
+    if (kind === "init") {
+        const branch = await text({
+            message: "Branch name?",
+            defaultValue: "main",
+            placeholder: "main",
+        });
+        if (isCancel(branch))
+            return null;
+        return { kind: "init", branch: branch || "main" };
+    }
+    if (kind === "clone") {
+        const url = await text({
+            message: "Repository URL?",
+            placeholder: "https://github.com/owner/repo.git",
+        });
+        if (isCancel(url))
+            return null;
+        return { kind: "clone", url: url };
+    }
+    if (kind === "gh-create") {
+        const name = await text({
+            message: "New repo name?",
+            defaultValue: basename(ctx.cwd),
+        });
+        if (isCancel(name))
+            return null;
+        const vis = await select({
+            message: "Visibility?",
+            options: [
+                { value: "private", label: "private" },
+                { value: "public", label: "public" },
+            ],
+            initialValue: "private",
+        });
+        if (isCancel(vis))
+            return null;
+        return {
+            kind: "gh-create",
+            name: name,
+            visibility: vis,
+        };
+    }
+    return { kind: "skip" };
+}
+export async function runWizard(ctx, userConfig, prefill) {
+    intro("airdy — project setup");
+    const agents = await multiselect({
+        message: "Which coding agent(s) to configure?",
+        options: allAdapters.map((a) => ({ value: a.id, label: a.id })),
+        initialValues: prefill.agents ?? ["claude-code"],
+        required: true,
+    });
+    if (isCancel(agents)) {
+        cancel("Cancelled");
+        return null;
+    }
+    const projectType = await select({
+        message: "Project type?",
+        options: PROJECT_TYPES,
+        initialValue: prefill.projectType ?? "minimal",
+    });
+    if (isCancel(projectType)) {
+        cancel("Cancelled");
+        return null;
+    }
+    const workflows = await multiselect({
+        message: "Development workflows?",
+        options: WORKFLOWS,
+        initialValues: prefill.workflows ?? ["none"],
+        required: true,
+    });
+    if (isCancel(workflows)) {
+        cancel("Cancelled");
+        return null;
+    }
+    const packages = mergePackages(userConfig);
+    const skillPackages = await multiselect({
+        message: "Skill packages? (space to toggle, enter to skip)",
+        options: Object.entries(packages).map(([name, p]) => ({
+            value: name,
+            label: name,
+            hint: p.description,
+        })),
+        initialValues: initialSkillPackages(prefill, projectType, packages),
+        required: false,
+    });
+    if (isCancel(skillPackages)) {
+        cancel("Cancelled");
+        return null;
+    }
+    const extraUrls = await text({
+        message: "Extra skills by git URL (comma-separated, optional; git installs land post-MVP)",
+        placeholder: "github.com/owner/repo/skills/foo",
+        defaultValue: "",
+    });
+    if (isCancel(extraUrls)) {
+        cancel("Cancelled");
+        return null;
+    }
+    const git = await promptGit(ctx, prefill);
+    if (!git) {
+        cancel("Cancelled");
+        return null;
+    }
+    const agentList = agents;
+    let launchAgent = agentList[0] ?? null;
+    let autoLaunch = true;
+    const PRINT_ONLY = "__print__";
+    if (agentList.length > 1) {
+        const launchOptions = [
+            ...agentList.map((id) => ({
+                value: id,
+                label: `launch ${id}`,
+            })),
+            { value: PRINT_ONLY, label: "print the command and exit" },
+        ];
+        const chosen = await select({
+            message: "Launch an agent now?",
+            options: launchOptions,
+            initialValue: (prefill.launchAgent ?? agentList[0]),
+        });
+        if (isCancel(chosen)) {
+            cancel("Cancelled");
+            return null;
+        }
+        if (chosen === PRINT_ONLY) {
+            autoLaunch = false; // keep launchAgent as the first agent for the printout
+        }
+        else {
+            launchAgent = chosen;
+        }
+    }
+    else if (launchAgent) {
+        const go = await confirm({ message: `Launch ${launchAgent} now?` });
+        if (isCancel(go)) {
+            cancel("Cancelled");
+            return null;
+        }
+        autoLaunch = go;
+    }
+    outro("Choices captured.");
+    return {
+        agents: agentList,
+        launchAgent,
+        projectType: projectType,
+        workflows: workflows,
+        skillPackages: skillPackages,
+        extraSkills: parseExtraSkillUrls(extraUrls),
+        git,
+        linkMode: prefill.linkMode ?? userConfig.preferences.linkMode ?? "link",
+        autoLaunch,
+    };
+}
+export async function confirmPlan() {
+    const ok = await confirm({ message: "Apply these changes?" });
+    if (isCancel(ok))
+        return false;
+    return ok;
+}

package/dist/skills/package.js

@@ -0,0 +1,53 @@
+import { homedir } from "node:os";
+import { join, basename } from "node:path";
+function expandHome(p) {
+    return p.startsWith("~") ? join(homedir(), p.slice(1)) : p;
+}
+function identity(ref) {
+    return [ref.source, ref.path, ref.repo, ref.subdir, ref.id]
+        .filter(Boolean)
+        .join("|");
+}
+export function resolveSkillRefs(packageNames, packages, extraSkills) {
+    const all = [];
+    for (const name of packageNames) {
+        const pkg = packages[name];
+        if (pkg)
+            all.push(...pkg.skills);
+    }
+    all.push(...extraSkills);
+    const seen = new Set();
+    const out = [];
+    for (const ref of all) {
+        const key = identity(ref);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(ref);
+    }
+    return out;
+}
+export function skillName(ref) {
+    if (ref.source === "local" && ref.path)
+        return basename(expandHome(ref.path));
+    if (ref.source === "git" && ref.subdir)
+        return basename(ref.subdir);
+    if (ref.source === "git" && ref.repo)
+        return basename(ref.repo);
+    if (ref.source === "marketplace" && ref.id)
+        return ref.id.split("/").pop();
+    throw new Error(`Cannot derive a skill name from ref: ${JSON.stringify(ref)}`);
+}
+export async function skillRefToActions(ref) {
+    const name = skillName(ref);
+    const dest = join(".agents", "skills", name);
+    if (ref.source === "local") {
+        return [{ type: "copy-dir", from: expandHome(ref.path), to: dest }];
+    }
+    if (ref.source === "git") {
+        console.warn(`airdy: git-source skill installs (${name} from ${ref.repo}) are coming post-MVP; skipped.`);
+        return [];
+    }
+    console.warn(`airdy: marketplace skills are not yet supported (${ref.id}); skipped. Use a git URL instead.`);
+    return [];
+}

package/dist/state/agentsetup.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+const STATE_VERSION = 1;
+export async function readState(root) {
+    try {
+        const raw = await readFile(join(root, "agentsetup.json"), "utf8");
+        const parsed = JSON.parse(raw);
+        // Old state files predate ownedPaths; default it so they still load.
+        return { ...parsed, ownedPaths: parsed.ownedPaths ?? [] };
+    }
+    catch {
+        return null;
+    }
+}
+export function stateAction(answers, ownedPaths) {
+    const state = {
+        version: STATE_VERSION,
+        agents: answers.agents,
+        launchAgent: answers.launchAgent,
+        projectType: answers.projectType,
+        workflows: answers.workflows,
+        skillPackages: answers.skillPackages,
+        linkMode: answers.linkMode,
+        ownedPaths,
+    };
+    return {
+        type: "write-file",
+        path: "agentsetup.json",
+        mode: "overwrite",
+        contents: JSON.stringify(state, null, 2) + "\n",
+    };
+}
+export function answersFromState(state) {
+    return {
+        agents: state.agents,
+        launchAgent: state.launchAgent,
+        projectType: state.projectType,
+        workflows: state.workflows,
+        skillPackages: state.skillPackages,
+        linkMode: state.linkMode,
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+export function getVersion() {
+    const url = new URL("../package.json", import.meta.url);
+    const pkg = JSON.parse(readFileSync(url, "utf8"));
+    return pkg.version;
+}