peer-ai 1.0.0-next.0

package/dist/detect.js

@@ -0,0 +1,459 @@
+// Reads a repository and works out what it can without asking: the project's name, whether
+// it is new or existing, which AI tools are set up, the git host, its CI, and the parts it is
+// made of, with where each one deploys. Everything found here is a proposal; `init` shows it
+// to the user before writing anything, and nothing that isn't found is assumed.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { CONFIG_FILE } from "peer-ai-workflow";
+export { CONFIG_FILE };
+const PROJECT_MARKERS = [
+    "package.json",
+    "pyproject.toml",
+    "requirements.txt",
+    "go.mod",
+    "Cargo.toml",
+    "pubspec.yaml",
+    "Gemfile",
+    "composer.json",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "Package.swift",
+    "Podfile",
+    "mix.exs",
+    "src",
+    "app",
+    "lib",
+];
+const WORKSPACE_DIRS = ["apps", "packages", "services", "libs"];
+const INFRA_DIRS = [
+    "infra",
+    "infrastructure",
+    "terraform",
+    "deploy",
+    "deployment",
+    "deployments",
+    "ops",
+    "devops",
+    "k8s",
+    "kubernetes",
+    "helm",
+    "charts",
+    "cdk",
+    "pulumi",
+];
+// Order matters: the first match decides the kind, so infrastructure, mobile and desktop
+// frameworks come before the web frameworks they may be built with.
+const NODE_FRAMEWORKS = [
+    ["aws-cdk-lib", "aws-cdk", "infrastructure"],
+    ["cdktf", "cdktf", "infrastructure"],
+    ["@pulumi/pulumi", "pulumi", "infrastructure"],
+    ["expo", "expo", "mobile"],
+    ["react-native", "react-native", "mobile"],
+    ["electron", "electron", "desktop"],
+    ["@tauri-apps/api", "tauri", "desktop"],
+    ["next", "next", "web"],
+    ["nuxt", "nuxt", "web"],
+    ["@sveltejs/kit", "sveltekit", "web"],
+    ["@angular/core", "angular", "web"],
+    ["astro", "astro", "web"],
+    ["vue", "vue", "web"],
+    ["svelte", "svelte", "web"],
+    ["react", "react", "web"],
+    ["vite", "vite", "web"],
+    ["@nestjs/core", "nest", "backend"],
+    ["express", "express", "backend"],
+    ["fastify", "fastify", "backend"],
+    ["hono", "hono", "backend"],
+    ["koa", "koa", "backend"],
+];
+// Backend frameworks in other languages, found by name in the project's dependency file. A
+// project whose frameworks aren't listed is still recognised by its language.
+const PYTHON_FRAMEWORKS = ["fastapi", "django", "flask"];
+const GO_FRAMEWORKS = [
+    ["github.com/gin-gonic/gin", "gin"],
+    ["github.com/labstack/echo", "echo"],
+    ["github.com/gofiber/fiber", "fiber"],
+    ["github.com/go-chi/chi", "chi"],
+];
+const RUST_FRAMEWORKS = [
+    ["axum", "axum"],
+    ["actix-web", "actix"],
+    ["rocket", "rocket"],
+    ["warp", "warp"],
+];
+const JVM_FRAMEWORKS = ["spring", "ktor", "quarkus", "micronaut"];
+const RUBY_FRAMEWORKS = ["rails", "sinatra", "hanami"];
+const PHP_FRAMEWORKS = [
+    ["laravel", "laravel"],
+    ["symfony/framework-bundle", "symfony"],
+    ["slim/slim", "slim"],
+];
+// Infrastructure as code, recognised by its files rather than by where it lives.
+const IAC_SIGNATURES = [
+    [(file) => file.endsWith(".tf") || file.endsWith(".tf.json"), "terraform"],
+    [(file) => file === "Pulumi.yaml" || file === "Pulumi.yml", "pulumi"],
+    [(file) => file === "cdk.json", "aws-cdk"],
+    [(file) => file === "Chart.yaml", "helm"],
+    [(file) => file === "kustomization.yaml" || file === "kustomization.yml", "kustomize"],
+    [(file) => file === "serverless.yml" || file === "serverless.yaml", "serverless"],
+    [(file) => file === "samconfig.toml", "aws-sam"],
+    [(file) => /\.cfn\.(ya?ml|json)$/.test(file), "cloudformation"],
+    [(file) => file.endsWith(".bicep"), "bicep"],
+    [(file) => file === "ansible.cfg" || file === "playbook.yml" || file === "site.yml", "ansible"],
+];
+const DOCKER_FILE = /^(Dockerfile|docker-compose.*\.ya?ml|compose\.ya?ml)$|\.Dockerfile$/;
+// A platform's config file in a part's folder says where that part deploys. More specific
+// platforms come first; a bare Dockerfile only says it ships as a container.
+const DEPLOY_TARGETS = [
+    ["vercel.json", "vercel"],
+    ["netlify.toml", "netlify"],
+    ["fly.toml", "fly"],
+    ["render.yaml", "render"],
+    ["railway.json", "railway"],
+    ["railway.toml", "railway"],
+    ["wrangler.toml", "cloudflare-workers"],
+    ["wrangler.json", "cloudflare-workers"],
+    ["wrangler.jsonc", "cloudflare-workers"],
+    ["firebase.json", "firebase"],
+    ["amplify.yml", "aws-amplify"],
+    ["eas.json", "expo-eas"],
+    ["serverless.yml", "serverless"],
+    ["serverless.yaml", "serverless"],
+    ["Procfile", "heroku"],
+    ["app.yaml", "gcp-app-engine"],
+    ["fastlane", "fastlane"],
+    ["Dockerfile", "container"],
+];
+const PIPELINES = [
+    [".github/workflows", true],
+    [".gitlab-ci.yml", false],
+    ["Jenkinsfile", false],
+    ["bitbucket-pipelines.yml", false],
+    ["azure-pipelines.yml", false],
+    [".circleci", true],
+    [".buildkite", true],
+    [".drone.yml", false],
+    [".travis.yml", false],
+    ["cloudbuild.yaml", false],
+    ["codemagic.yaml", false],
+    ["bitrise.yml", false],
+];
+const isDir = (path) => existsSync(path) && statSync(path).isDirectory();
+const readText = (path) => (existsSync(path) ? readFileSync(path, "utf8") : "");
+const listDir = (dir) => (isDir(dir) ? readdirSync(dir) : []);
+function readJson(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return typeof value === "object" && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function dependencyNames(pkg) {
+    const sections = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies];
+    return sections.flatMap((section) => (typeof section === "object" && section !== null ? Object.keys(section) : []));
+}
+export function slugify(text) {
+    const slug = text
+        .toLowerCase()
+        .replace(/^@[^/]+\//, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return /^[a-z]/.test(slug) ? slug : slug === "" ? "app" : `app-${slug}`;
+}
+function hasTypescript(dir) {
+    const pkg = readJson(join(dir, "package.json"));
+    return ((pkg !== undefined && dependencyNames(pkg).includes("typescript")) ||
+        existsSync(join(dir, "tsconfig.json")) ||
+        existsSync(join(dir, "tsconfig.base.json")));
+}
+/**
+ * File and folder names in a directory and its subdirectories, down to a depth. Infrastructure
+ * is often nested, such as terraform/envs/production/main.tf.
+ */
+function namesWithin(dir, depth) {
+    return listDir(dir).flatMap((entry) => {
+        const nested = depth > 1 && !entry.startsWith(".") && entry !== "node_modules" && isDir(join(dir, entry));
+        return nested ? [entry, ...namesWithin(join(dir, entry), depth - 1)] : [entry];
+    });
+}
+// In a monorepo, TypeScript is often installed once at the root rather than in each part.
+function detectNodeTrack(dir, inheritsTypescript) {
+    const pkg = readJson(join(dir, "package.json"));
+    if (pkg === undefined)
+        return undefined;
+    const deps = dependencyNames(pkg);
+    const stack = [];
+    if (inheritsTypescript || hasTypescript(dir))
+        stack.push("typescript");
+    let kind;
+    for (const [dependency, tag, frameworkKind] of NODE_FRAMEWORKS) {
+        if (!deps.includes(dependency))
+            continue;
+        stack.push(tag);
+        kind ??= frameworkKind;
+    }
+    kind ??= pkg.bin === undefined ? "library" : "cli";
+    if (!stack.includes("typescript"))
+        stack.unshift("javascript");
+    return { kind, stack };
+}
+/** A backend when it depends on one of its language's frameworks, otherwise a library. */
+function byFramework(language, manifest, frameworks) {
+    const framework = frameworks.find(([needle]) => manifest.includes(needle))?.[1];
+    return framework === undefined
+        ? { kind: "library", stack: [language] }
+        : { kind: "backend", stack: [language, framework] };
+}
+const named = (names) => names.map((name) => [name, name]);
+/** An application or library part, recognised by its language's project files. */
+function detectApp(dir, inheritsTypescript) {
+    const node = detectNodeTrack(dir, inheritsTypescript);
+    if (node !== undefined)
+        return node;
+    const python = `${readText(join(dir, "pyproject.toml"))}\n${readText(join(dir, "requirements.txt"))}`.toLowerCase();
+    if (python.trim() !== "")
+        return byFramework("python", python, named(PYTHON_FRAMEWORKS));
+    const pubspec = readText(join(dir, "pubspec.yaml"));
+    if (pubspec !== "") {
+        if (!pubspec.includes("flutter"))
+            return { kind: "library", stack: ["dart"] };
+        // A Flutter app has an entry point or platform folders; a Flutter package has neither.
+        const isApp = ["lib/main.dart", "android", "ios"].some((path) => existsSync(join(dir, path)));
+        return { kind: isApp ? "mobile" : "library", stack: ["dart", "flutter"] };
+    }
+    const gradle = readText(join(dir, "build.gradle.kts")) + readText(join(dir, "build.gradle"));
+    const maven = readText(join(dir, "pom.xml"));
+    if (gradle !== "" || maven !== "") {
+        const language = existsSync(join(dir, "build.gradle.kts")) ? "kotlin" : "java";
+        if (gradle.includes("com.android.application"))
+            return { kind: "mobile", stack: ["kotlin", "android"] };
+        const framework = JVM_FRAMEWORKS.find((name) => (gradle + maven).includes(name));
+        return { kind: "backend", stack: framework === undefined ? [language] : [language, framework] };
+    }
+    const csproj = listDir(dir).find((file) => file.endsWith(".csproj"));
+    if (csproj !== undefined) {
+        const project = readText(join(dir, csproj));
+        if (project.includes("<UseMaui>true"))
+            return { kind: "mobile", stack: ["csharp", "dotnet", "maui"] };
+        if (project.includes("Microsoft.NET.Sdk.BlazorWebAssembly")) {
+            return { kind: "web", stack: ["csharp", "dotnet", "blazor"] };
+        }
+        if (project.includes("Microsoft.NET.Sdk.Web"))
+            return { kind: "backend", stack: ["csharp", "dotnet", "aspnet"] };
+        return { kind: "library", stack: ["csharp", "dotnet"] };
+    }
+    if (listDir(dir).some((file) => file.endsWith(".xcodeproj")))
+        return { kind: "mobile", stack: ["swift", "ios"] };
+    const swiftPackage = readText(join(dir, "Package.swift"));
+    if (swiftPackage !== "")
+        return byFramework("swift", swiftPackage, [["vapor", "vapor"]]);
+    // A Go module is a backend even without a framework, since Go's own library serves HTTP.
+    const goMod = readText(join(dir, "go.mod"));
+    if (goMod !== "") {
+        const framework = GO_FRAMEWORKS.find(([module]) => goMod.includes(module))?.[1];
+        return { kind: "backend", stack: framework === undefined ? ["go"] : ["go", framework] };
+    }
+    const cargo = readText(join(dir, "Cargo.toml"));
+    if (cargo !== "") {
+        const framework = RUST_FRAMEWORKS.find(([crate]) => new RegExp(`^${crate}\\s*=`, "m").test(cargo))?.[1];
+        return framework === undefined
+            ? { kind: "other", stack: ["rust"] }
+            : { kind: "backend", stack: ["rust", framework] };
+    }
+    const gemfile = readText(join(dir, "Gemfile"));
+    if (gemfile !== "")
+        return byFramework("ruby", gemfile, named(RUBY_FRAMEWORKS));
+    const composer = readText(join(dir, "composer.json"));
+    if (composer !== "")
+        return byFramework("php", composer, PHP_FRAMEWORKS);
+    const mix = readText(join(dir, "mix.exs"));
+    if (mix !== "")
+        return byFramework("elixir", mix, [[":phoenix", "phoenix"]]);
+    return undefined;
+}
+/**
+ * Infrastructure as code. Docker files count only inside an infrastructure folder, so a
+ * docker-compose file used for local development is not mistaken for infrastructure.
+ */
+function detectInfrastructure(dir, options) {
+    const files = options.deep ? namesWithin(dir, 5) : listDir(dir);
+    const stack = IAC_SIGNATURES.filter(([matches]) => files.some(matches)).map(([, tag]) => tag);
+    if (["k8s", "kubernetes"].includes(basename(dir)) && files.some((file) => /\.ya?ml$/.test(file))) {
+        stack.push("kubernetes");
+    }
+    if (options.includeDocker && files.some((file) => DOCKER_FILE.test(file)))
+        stack.push("docker");
+    return stack.length === 0 ? undefined : { kind: "infrastructure", stack };
+}
+export function detectDeploy(dir) {
+    for (const [file, target] of DEPLOY_TARGETS) {
+        if (!existsSync(join(dir, file)))
+            continue;
+        if (file === "app.yaml" && !readText(join(dir, file)).includes("runtime:"))
+            continue;
+        return target;
+    }
+    return undefined;
+}
+function withDeploy(track, dir) {
+    if (track.kind === "infrastructure" || track.kind === "library")
+        return track;
+    const deploy = detectDeploy(dir);
+    return deploy === undefined ? track : { ...track, deploy };
+}
+function isWorkspaceRoot(root) {
+    const markers = ["pnpm-workspace.yaml", "turbo.json", "nx.json", "lerna.json", "go.work"];
+    if (markers.some((file) => existsSync(join(root, file))))
+        return true;
+    // A Cargo workspace root with no package of its own only groups the crates inside it.
+    const cargo = readText(join(root, "Cargo.toml"));
+    if (/^\[workspace\]/m.test(cargo) && !/^\[package\]/m.test(cargo))
+        return true;
+    return readJson(join(root, "package.json"))?.workspaces !== undefined;
+}
+const tomlValue = (text, key) => new RegExp(`^\\s*${key}\\s*=\\s*"([^"]+)"`, "m").exec(text)?.[1];
+/** The project's name from its own project file, in whichever language it's written. */
+export function detectName(root) {
+    const text = (file) => readText(join(root, file));
+    const pkgName = readJson(join(root, "package.json"))?.name;
+    const composerName = readJson(join(root, "composer.json"))?.name;
+    const goModule = /^module\s+(\S+)/m.exec(text("go.mod"))?.[1]?.replace(/\/v\d+$/, "");
+    const candidates = [
+        typeof pkgName === "string" ? pkgName.replace(/^@[^/]+\//, "") : undefined,
+        tomlValue(text("pyproject.toml"), "name"),
+        tomlValue(text("Cargo.toml"), "name"),
+        goModule?.split("/").pop(),
+        typeof composerName === "string" ? composerName.split("/").pop() : undefined,
+        /^name:\s*["']?([\w-]+)/m.exec(text("pubspec.yaml"))?.[1],
+        /rootProject\.name\s*=\s*["']([^"']+)["']/.exec(text("settings.gradle.kts") + text("settings.gradle"))?.[1],
+    ];
+    return candidates.find((name) => name !== undefined && name !== "") ?? basename(root);
+}
+function detectDescription(root) {
+    const description = readJson(join(root, "package.json"))?.description;
+    if (typeof description === "string" && description !== "")
+        return description;
+    return (tomlValue(readText(join(root, "pyproject.toml")), "description") ??
+        tomlValue(readText(join(root, "Cargo.toml")), "description"));
+}
+export function detectTracks(root, projectName) {
+    const found = [];
+    if (!isWorkspaceRoot(root)) {
+        // The root is one app, or a repository that is itself an infrastructure project.
+        const app = detectApp(root, false);
+        const rootTrack = app === undefined ? detectInfrastructure(root, { deep: false, includeDocker: false }) : withDeploy(app, root);
+        if (rootTrack !== undefined)
+            found.push({ track: rootTrack, name: projectName });
+    }
+    const rootTypescript = hasTypescript(root);
+    for (const workspace of WORKSPACE_DIRS) {
+        for (const child of listDir(join(root, workspace)).sort()) {
+            const dir = join(root, workspace, child);
+            if (child.startsWith(".") || !isDir(dir))
+                continue;
+            const app = detectApp(dir, rootTypescript);
+            const track = app === undefined ? detectInfrastructure(dir, { deep: false, includeDocker: false }) : withDeploy(app, dir);
+            if (track !== undefined)
+                found.push({ path: `${workspace}/${child}`, track, name: child });
+        }
+    }
+    for (const infra of INFRA_DIRS) {
+        const dir = join(root, infra);
+        if (!isDir(dir))
+            continue;
+        const track = detectInfrastructure(dir, { deep: true, includeDocker: true }) ?? detectApp(dir, rootTypescript);
+        if (track !== undefined)
+            found.push({ path: infra, track, name: infra });
+    }
+    const used = new Set();
+    return found.map(({ path, track, name }) => {
+        let id = slugify(name);
+        for (let n = 2; used.has(id); n++)
+            id = `${slugify(name)}-${String(n)}`;
+        used.add(id);
+        return path === undefined ? { id, ...track } : { id, path, ...track };
+    });
+}
+export function detectDelivery(root) {
+    for (const [path, directory] of PIPELINES) {
+        const full = join(root, path);
+        const present = directory ? listDir(full).some((file) => /\.ya?ml$/.test(file)) : existsSync(full);
+        if (present)
+            return { ci: "existing", pipeline: directory ? `${path}/` : path };
+    }
+    return undefined;
+}
+export function detectTools(root) {
+    const tools = [];
+    if (existsSync(join(root, "CLAUDE.md")) || isDir(join(root, ".claude")))
+        tools.push("claude-code");
+    if (isDir(join(root, ".codex")))
+        tools.push("codex");
+    if (isDir(join(root, ".cursor")) || existsSync(join(root, ".cursorrules")))
+        tools.push("cursor");
+    if (existsSync(join(root, ".github", "copilot-instructions.md")))
+        tools.push("copilot");
+    if (existsSync(join(root, "GEMINI.md")) || isDir(join(root, ".gemini")))
+        tools.push("gemini-cli");
+    return tools;
+}
+/** The host name of a git remote, from an https, ssh:// or scp-style (git@host:path) URL. */
+export function remoteHostname(url) {
+    const scp = /^[^@/\s]+@([^:/\s]+):/.exec(url);
+    if (scp?.[1] !== undefined)
+        return scp[1].toLowerCase();
+    try {
+        return new URL(url).hostname.toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Matched on the parsed host name against each service's real domain, never on the whole URL,
+// so a URL that merely contains "github.com" is not mistaken for GitHub. A self-hosted server
+// cannot be recognised reliably from its name, so it is recorded as "other" for the user to set.
+export function classifyHost(hostname) {
+    if (hostname === undefined)
+        return "other";
+    const is = (domain) => hostname === domain || hostname.endsWith(`.${domain}`);
+    if (is("github.com"))
+        return "github";
+    if (is("gitlab.com"))
+        return "gitlab";
+    if (is("bitbucket.org"))
+        return "bitbucket";
+    if (is("dev.azure.com") || is("visualstudio.com"))
+        return "azure-devops";
+    return "other";
+}
+export function detectRepo(root) {
+    let url;
+    try {
+        url = execFileSync("git", ["remote", "get-url", "origin"], { cwd: root, encoding: "utf8", stdio: "pipe" }).trim();
+    }
+    catch {
+        return { remote: null };
+    }
+    return { host: classifyHost(remoteHostname(url)), remote: "origin" };
+}
+export function detect(root) {
+    const name = detectName(root);
+    const tracks = detectTracks(root, name);
+    const description = detectDescription(root);
+    const delivery = detectDelivery(root);
+    const existing = tracks.length > 0 || PROJECT_MARKERS.some((marker) => existsSync(join(root, marker)));
+    return {
+        name,
+        ...(description === undefined ? {} : { description }),
+        origin: existing ? "existing" : "new",
+        tools: detectTools(root),
+        repo: detectRepo(root),
+        ...(delivery === undefined ? {} : { delivery }),
+        tracks,
+        hasConfig: existsSync(join(root, CONFIG_FILE)),
+    };
+}

package/dist/doctor.d.ts

@@ -0,0 +1,36 @@
+import { type PeerAiConfig } from "peer-ai-workflow";
+import { type Check } from "./checks.ts";
+import type { Output } from "./init.ts";
+export interface Diagnosis {
+    name: string;
+    ok: boolean;
+    checks: Check[];
+}
+export interface DiagnoseOptions {
+    /** Check the rendered skills too. CI never has them, since they stay out of git, unless the project commits them. */
+    skills?: boolean;
+}
+export declare function checkConfig(root: string): {
+    check: Check;
+    config?: PeerAiConfig;
+};
+/** Each track's folder exists, and every part found in the repository belongs to a track. */
+export declare function checkTracks(root: string, config: PeerAiConfig): Check[];
+/**
+ * Every rule the project sets aside or changes, listed so nothing is switched off silently (RFC
+ * 0003). An id with a core or stack profile prefix must be one of Peer AI's rules, and a changed
+ * rule must have a value to change (RFC 0006); other prefixes belong to project add-ons, which
+ * are listed as they are.
+ */
+export declare function checkStandards(config: PeerAiConfig, today: string): Check[];
+/** Every work item is valid, named after its id, and on a track the config has. */
+export declare function checkWorkItems(root: string, config: PeerAiConfig | undefined): Check[];
+export declare function diagnose(root: string, nodeVersion?: string, today?: Date, options?: DiagnoseOptions): Diagnosis;
+export declare function formatDiagnosis(diagnosis: Diagnosis): string[];
+export interface DoctorOptions {
+    cwd: string;
+    json: boolean;
+    nodeVersion?: string;
+}
+/** Exit code 0 when nothing failed, even with warnings; 1 when something failed. */
+export declare function runDoctor(options: DoctorOptions, out: Output): number;