airdy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raiy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# airdy
+
+airdy is an interactive setup wizard for coding-agent projects. Run it inside a
+project directory and it asks which agent(s) to configure, the project type,
+workflows, skill packages, and a git strategy, then writes the project-level
+config files those choices imply and optionally launches the chosen agent. It
+writes only project files and never scaffolds application source code.
+
+## Quickstart
+
+```bash
+npx airdy
+```
+
+Run it in the directory you want to set up. The wizard walks these steps:
+
+1. Which coding agent(s) to configure (`claude-code`, `codex`).
+2. Project type (web, mobile-app, backend, desktop, oss-fork, minimal) — this
+   pre-selects the suggested skill packages for that type.
+3. Development workflows (superpowers, verify-loop, ship-gate, none).
+4. Skill packages to install.
+5. Extra skills by git URL (optional; git installs land post-MVP).
+6. Git setup (`git init`, `git clone`, `gh repo create`, or skip).
+7. Which agent to launch — or print the launch command and exit.
+
+## Flags
+
+| Flag              | Effect                                                   |
+| ----------------- | -------------------------------------------------------- |
+| `-y`, `--yes`     | Non-interactive; requires `--config`.                    |
+| `--config <file>` | Answers JSON for non-interactive mode.                   |
+| `--dry-run`       | Print the plan and the launch command; write nothing.    |
+| `--copy`          | Copy skills into `.claude/skills` instead of symlinking. |
+| `-v`, `--version` | Print the version.                                       |
+| `-h`, `--help`    | Print help.                                              |
+
+## Configuration
+
+Optional user config lives at `~/.config/airdy/config.json`:
+
+- `packages` — named skill packages (merged over the built-ins).
+- `presetSources` — directories holding workflow modules loaded by path.
+- `preferences` — defaults such as `linkMode` (`link` or `copy`).
+
+## What it writes
+
+Depending on the selections, airdy writes some subset of:
+
+| Path                    | Purpose                                                     |
+| ----------------------- | ----------------------------------------------------------- |
+| `AGENTS.md`             | Canonical agent instructions (workflow sections merged in). |
+| `CLAUDE.md`             | One-line pointer to AGENTS.md (claude-code only).           |
+| `.gitignore`            | Project ignore rules (on `git init` / `gh repo create`).    |
+| `.agents/skills/<name>` | Installed skill directories.                                |
+| `.claude/skills`        | Symlink (or copy) to `.agents/skills` (claude-code).        |
+| `.claude/settings.json` | Workflow-module hooks (deep-merged with existing).          |
+| `agentsetup.json`       | airdy's own state: your selections plus the paths it owns.  |
+
+## Re-runs, idempotency, and conflicts
+
+airdy is safe to re-run. Marker-based markdown sections and JSON settings are
+merged idempotently, so re-running does not duplicate content. `agentsetup.json`
+records the exact paths airdy has written (`ownedPaths`); a file airdy did not
+create is never overwritten silently — in interactive mode you are prompted to
+skip, overwrite, or merge, and under `--yes` such files are skipped and
+reported.
+
+## Security
+
+Every write destination is confined to the project directory. Containment is
+checked both lexically and via `realpath` — covering both a symlinked ancestor
+directory and the destination path itself being a symlink — so a symlink
+anywhere on the path cannot redirect a write outside the project tree. airdy
+never touches global config (`~/.claude`, `~/.codex`).
+
+Known limitation: containment is checked before each write, not atomically
+with it (TOCTOU). Exploiting the gap requires local hostile timing (something
+racing to swap in a symlink between the check and the write) rather than a
+remote or data-only attack.
+
+## Scope
+
+This is the MVP. Local skill packages install by copying a directory. Git-source
+and marketplace skill installs are stubbed and land post-MVP.

package/bin/airdy.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from "../dist/main.js";
+main(process.argv.slice(2), process.cwd())
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(String(err?.message ?? err));
+    process.exit(1);
+  });

package/dist/adapters/claude-code.js

@@ -0,0 +1,41 @@
+const CLAUDE_POINTER = `See [AGENTS.md](./AGENTS.md) for all project context, conventions, and workflows.
+
+This file is only a pointer. Edit AGENTS.md, not this file.
+`;
+function hasSkills(answers) {
+    return answers.skillPackages.length > 0 || answers.extraSkills.length > 0;
+}
+export const claudeCodeAdapter = {
+    id: "claude-code",
+    cliName: "claude",
+    contribute(answers, _ctx) {
+        const actions = [
+            {
+                type: "write-file",
+                path: "CLAUDE.md",
+                mode: "create",
+                contents: CLAUDE_POINTER,
+            },
+        ];
+        if (hasSkills(answers)) {
+            if (answers.linkMode === "link") {
+                actions.push({
+                    type: "symlink",
+                    path: ".claude/skills",
+                    target: "../.agents/skills",
+                });
+            }
+            else {
+                actions.push({
+                    type: "copy-dir",
+                    from: ".agents/skills",
+                    to: ".claude/skills",
+                });
+            }
+        }
+        return actions;
+    },
+    launchCommand(_ctx) {
+        return { cmd: "claude", args: [] };
+    },
+};

package/dist/adapters/codex.js

@@ -0,0 +1,11 @@
+export const codexAdapter = {
+    id: "codex",
+    cliName: "codex",
+    contribute(_answers, _ctx) {
+        return [];
+    },
+    launchCommand(_ctx) {
+        return { cmd: "codex", args: [] };
+    },
+    trustNote: "Codex ignores an untrusted project's .codex/ directory on first launch. Run codex once and trust this folder for project config to take effect.",
+};

package/dist/adapters/index.js

@@ -0,0 +1,9 @@
+import { claudeCodeAdapter } from "./claude-code.js";
+import { codexAdapter } from "./codex.js";
+export const allAdapters = [claudeCodeAdapter, codexAdapter];
+export function getAdapter(id) {
+    const found = allAdapters.find((a) => a.id === id);
+    if (!found)
+        throw new Error(`No adapter registered for agent "${id}"`);
+    return found;
+}

package/dist/adapters/types.js

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

package/dist/cli/args.js

@@ -0,0 +1,45 @@
+export function parseArgs(argv) {
+    const out = {
+        yes: false,
+        configPath: null,
+        dryRun: false,
+        copy: false,
+        version: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--yes":
+            case "-y":
+                out.yes = true;
+                break;
+            case "--config": {
+                const value = argv[i + 1];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--config requires a file path");
+                }
+                out.configPath = value;
+                i++;
+                break;
+            }
+            case "--dry-run":
+                out.dryRun = true;
+                break;
+            case "--copy":
+                out.copy = true;
+                break;
+            case "--version":
+            case "-v":
+                out.version = true;
+                break;
+            case "--help":
+            case "-h":
+                out.help = true;
+                break;
+            default:
+                throw new Error(`unknown flag: ${arg}`);
+        }
+    }
+    return out;
+}

package/dist/config/user.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+export const BUILTIN_PACKAGES = {
+    core: { description: "Baseline skills", skills: [] },
+    web: { description: "Web development", skills: [] },
+    backend: { description: "Backend development", skills: [] },
+    mobile: { description: "Mobile development", skills: [] },
+    desktop: { description: "Desktop development", skills: [] },
+};
+export async function loadUserConfig(home = homedir()) {
+    const path = join(home, ".config", "airdy", "config.json");
+    try {
+        const raw = JSON.parse(await readFile(path, "utf8"));
+        return {
+            packages: raw.packages ?? {},
+            preferences: raw.preferences ?? {},
+            presetSources: raw.presetSources ?? [],
+        };
+    }
+    catch {
+        return { packages: {}, preferences: {}, presetSources: [] };
+    }
+}
+export function mergePackages(config) {
+    return { ...BUILTIN_PACKAGES, ...config.packages };
+}
+export async function loadAnswersFromConfig(configPath, root, copy) {
+    const abs = isAbsolute(configPath) ? configPath : join(root, configPath);
+    const raw = JSON.parse(await readFile(abs, "utf8"));
+    if (!raw.agents || raw.agents.length === 0) {
+        throw new Error("config: 'agents' must be a non-empty array");
+    }
+    if (!raw.projectType) {
+        throw new Error("config: 'projectType' is required");
+    }
+    const agents = raw.agents;
+    return {
+        agents,
+        launchAgent: raw.launchAgent ?? agents[0],
+        projectType: raw.projectType,
+        workflows: raw.workflows ?? ["none"],
+        skillPackages: raw.skillPackages ?? [],
+        extraSkills: raw.extraSkills ?? [],
+        git: raw.git ?? { kind: "skip" },
+        linkMode: raw.linkMode ?? (copy ? "copy" : "link"),
+        autoLaunch: raw.autoLaunch ?? true,
+    };
+}

package/dist/context.js

@@ -0,0 +1,69 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const pExecFile = promisify(execFile);
+export async function commandExists(name) {
+    const finder = process.platform === "win32" ? "where" : "which";
+    try {
+        await pExecFile(finder, [name]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function detectContext(cwd) {
+    let entries = [];
+    try {
+        entries = await readdir(cwd);
+    }
+    catch {
+        entries = [];
+    }
+    const visible = entries.filter((e) => e !== ".git");
+    const [git, claude, codex, gh] = await Promise.all([
+        commandExists("git"),
+        commandExists("claude"),
+        commandExists("codex"),
+        commandExists("gh"),
+    ]);
+    return {
+        cwd,
+        isEmpty: visible.length === 0,
+        isGitRepo: await exists(join(cwd, ".git")),
+        hasAgentsMd: await exists(join(cwd, "AGENTS.md")),
+        hasClaudeMd: await exists(join(cwd, "CLAUDE.md")),
+        hasClaudeDir: await exists(join(cwd, ".claude")),
+        hasAgentSetup: await exists(join(cwd, "agentsetup.json")),
+        cli: { git, claude, codex, gh },
+    };
+}
+export function checkPreflight(answers, ctx) {
+    const warnings = [];
+    const needsGit = answers.git.kind === "init" ||
+        answers.git.kind === "clone" ||
+        answers.git.kind === "gh-create";
+    if (needsGit && !ctx.cli.git) {
+        warnings.push("git is not installed — the git step will be skipped. Install: https://git-scm.com");
+    }
+    if (answers.git.kind === "gh-create" && !ctx.cli.gh) {
+        warnings.push("gh (GitHub CLI) is not installed — cannot create a remote repo. Install: https://cli.github.com");
+    }
+    if (answers.launchAgent === "claude-code" && !ctx.cli.claude) {
+        warnings.push("claude CLI not found — files will be written but the agent will not auto-launch.");
+    }
+    if (answers.launchAgent === "codex" && !ctx.cli.codex) {
+        warnings.push("codex CLI not found — files will be written but the agent will not auto-launch.");
+    }
+    return warnings;
+}

package/dist/git/steps.js

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const pExecFile = promisify(execFile);
+export async function preGit(action, root) {
+    switch (action.kind) {
+        case "init":
+            await pExecFile("git", ["init", "-b", action.branch], { cwd: root });
+            return;
+        case "gh-create":
+            await pExecFile("git", ["init", "-b", "main"], { cwd: root });
+            return;
+        case "clone":
+            await pExecFile("git", ["clone", action.url, "."], { cwd: root });
+            return;
+        case "skip":
+            return;
+    }
+}
+export async function postGit(action, root) {
+    if (action.kind === "gh-create") {
+        await pExecFile("gh", [
+            "repo",
+            "create",
+            action.name,
+            `--${action.visibility}`,
+            "--source",
+            ".",
+            "--remote",
+            "origin",
+        ], { cwd: root });
+    }
+}