code-ai-installer 1.0.1

package/README.md

@@ -0,0 +1,91 @@
+# code-ai installer
+
+CLI for installing your `agents/` and `.agents/skills/` assets into AI-specific layouts.
+
+## Supported targets
+- `vscode-copilot`
+- `gpt-codex`
+- `claude`
+- `qwen-3.5`
+- `google-antugravity`
+
+## Install
+```bash
+npm install
+npm run build
+```
+
+## Global install
+```bash
+# from npm registry
+npm install -g code-ai-installer
+# or
+pnpm add -g code-ai-installer
+# or
+yarn global add code-ai-installer
+# or
+bun add -g code-ai-installer
+
+# verify binary in system terminal
+code-ai --help
+```
+
+```bash
+# install globally from local repository
+npm install -g .
+code-ai --help
+```
+
+## Usage
+```bash
+# interactive wizard (recommended)
+code-ai
+
+# list targets
+code-ai targets
+
+# list available agents and skills from current repository
+code-ai list
+
+# health checks
+code-ai doctor --target claude
+
+# dry-run install (default)
+code-ai install --target claude --agents conductor,reviewer --skills board,security_review
+
+# apply install with overwrite
+code-ai install --target claude --agents all --skills all --overwrite --apply
+
+# strict mode: require explicit target hints in agent/skill files
+code-ai install --target claude --agents all --skills all --strict-hints --apply
+
+# uninstall preview
+code-ai uninstall --target claude
+
+# uninstall apply
+code-ai uninstall --target claude --apply
+```
+
+## What gets generated
+- Root orchestration mirror: `AGENTS.md`
+- Target instruction file:
+  - Copilot: `.github/copilot-instructions.md`
+  - GPT Codex: `CODEX.md`
+  - Claude: `CLAUDE.md`
+  - Qwen: `QWEN.md`
+  - Google Antugravity: `GEMINI.md`
+- Agent files copied to target-specific agents directory.
+- Skill files copied to target-specific skills directory.
+- Markdown content is normalized per target (model-specific hint comments like `codex:` are transformed).
+  - `codex reasoning` is mapped to target-native hints (`claude thinking`, `qwen reasoning_effort`, `gemini reasoning`).
+
+## Safety model
+- Default mode is `dry-run`.
+- Backup is created before writes under `.code-ai-installer/backups/<target>/<timestamp>/`.
+- State is tracked in `.code-ai-installer/state/<target>.json` for uninstall.
+- Rollback restores previous files on install failure.
+- Optional strict policy: `--strict-hints` fails install if selected agent/skill files don't contain explicit target-native hint markers.
+
+## Notes
+- Target aliases are accepted: `copilot`, `codex`, `claude`, `qwen`, `google`, `antigravity`.
+- If your AI tool requires a custom location, pass `--destination <path>`.

package/dist/catalog.d.ts

@@ -0,0 +1,27 @@
+import type { SourceCatalog } from "./types.js";
+/**
+ * Builds source catalog from repository folders and validates required paths.
+ * @param projectDir Absolute path to repository root.
+ * @returns Source catalog including orchestrator, agents, and skills.
+ */
+export declare function loadSourceCatalog(projectDir: string): Promise<SourceCatalog>;
+/**
+ * Returns available role names from catalog map.
+ * @param catalog Source catalog.
+ * @returns Sorted agent names.
+ */
+export declare function listAgentNames(catalog: SourceCatalog): string[];
+/**
+ * Returns available skill names from catalog map.
+ * @param catalog Source catalog.
+ * @returns Sorted skill names.
+ */
+export declare function listSkillNames(catalog: SourceCatalog): string[];
+/**
+ * Resolves selected names, expanding "all" and validating values.
+ * @param selected Comma-separated user selection string.
+ * @param available List of available names.
+ * @param entityLabel Human-readable entity label for errors.
+ * @returns Validated selection array.
+ */
+export declare function resolveSelection(selected: string, available: string[], entityLabel: string): string[];

package/dist/catalog.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { z } from "zod";
+const fileNameSchema = z.string().min(1);
+/**
+ * Builds source catalog from repository folders and validates required paths.
+ * @param projectDir Absolute path to repository root.
+ * @returns Source catalog including orchestrator, agents, and skills.
+ */
+export async function loadSourceCatalog(projectDir) {
+    const orchestratorPath = path.join(projectDir, "AGENTS.md");
+    const agentsDir = path.join(projectDir, "agents");
+    const legacySkillsDir = path.join(projectDir, ".agents", "skills");
+    const flatSkillsDir = path.join(projectDir, ".agents");
+    if (!(await fs.pathExists(orchestratorPath))) {
+        throw new Error(`Missing AGENTS.md at ${orchestratorPath}`);
+    }
+    if (!(await fs.pathExists(agentsDir))) {
+        throw new Error(`Missing agents directory at ${agentsDir}`);
+    }
+    const hasLegacySkillsDir = await fs.pathExists(legacySkillsDir);
+    const hasFlatSkillsDir = await fs.pathExists(flatSkillsDir);
+    if (!hasLegacySkillsDir && !hasFlatSkillsDir) {
+        throw new Error(`Missing skills directory. Checked ${legacySkillsDir} and ${flatSkillsDir}`);
+    }
+    const agentFiles = await mapAgentFiles(agentsDir);
+    const skillFiles = {};
+    if (hasLegacySkillsDir) {
+        Object.assign(skillFiles, await mapSkillFilesFromNestedRoot(legacySkillsDir));
+    }
+    if (hasFlatSkillsDir) {
+        Object.assign(skillFiles, await mapSkillFilesFromFlatRoot(flatSkillsDir));
+    }
+    return {
+        rootDir: projectDir,
+        orchestratorPath,
+        agentFiles,
+        skillFiles,
+    };
+}
+/**
+ * Returns available role names from catalog map.
+ * @param catalog Source catalog.
+ * @returns Sorted agent names.
+ */
+export function listAgentNames(catalog) {
+    return Object.keys(catalog.agentFiles).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Returns available skill names from catalog map.
+ * @param catalog Source catalog.
+ * @returns Sorted skill names.
+ */
+export function listSkillNames(catalog) {
+    return Object.keys(catalog.skillFiles).sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Resolves selected names, expanding "all" and validating values.
+ * @param selected Comma-separated user selection string.
+ * @param available List of available names.
+ * @param entityLabel Human-readable entity label for errors.
+ * @returns Validated selection array.
+ */
+export function resolveSelection(selected, available, entityLabel) {
+    const normalized = selected
+        .split(",")
+        .map((name) => name.trim())
+        .filter(Boolean);
+    if (normalized.length === 0 || normalized.includes("all")) {
+        return [...available];
+    }
+    const missing = normalized.filter((name) => !available.includes(name));
+    if (missing.length > 0) {
+        throw new Error(`Unknown ${entityLabel}: ${missing.join(", ")}`);
+    }
+    return normalized;
+}
+/**
+ * Maps agent markdown files from agents directory.
+ * @param agentsDir Absolute agents directory path.
+ * @returns Agent name to file path mapping.
+ */
+async function mapAgentFiles(agentsDir) {
+    const entries = await fs.readdir(agentsDir);
+    const result = {};
+    for (const entry of entries) {
+        fileNameSchema.parse(entry);
+        if (!entry.endsWith(".md")) {
+            continue;
+        }
+        const key = entry.replace(/\.md$/i, "");
+        result[key] = path.join(agentsDir, entry);
+    }
+    return result;
+}
+/**
+ * Maps skills from nested skill directories ending with SKILL.md.
+ * @param skillsDir Absolute skills directory path.
+ * @returns Skill name to SKILL.md path mapping.
+ */
+async function mapSkillFilesFromNestedRoot(skillsDir) {
+    const entries = await fs.readdir(skillsDir);
+    const result = {};
+    for (const entry of entries) {
+        fileNameSchema.parse(entry);
+        const skillFile = path.join(skillsDir, entry, "SKILL.md");
+        if (!(await fs.pathExists(skillFile))) {
+            continue;
+        }
+        result[entry] = skillFile;
+    }
+    return result;
+}
+/**
+ * Maps skills from nested .agents folders that contain SKILL.md.
+ * @param agentsRoot Absolute .agents directory path.
+ * @returns Skill name to SKILL.md path mapping.
+ */
+async function mapSkillFilesFromFlatRoot(agentsRoot) {
+    const entries = await fs.readdir(agentsRoot);
+    const result = {};
+    for (const entry of entries) {
+        fileNameSchema.parse(entry);
+        if (entry === "skills") {
+            continue;
+        }
+        const skillFile = path.join(agentsRoot, entry, "SKILL.md");
+        if (!(await fs.pathExists(skillFile))) {
+            continue;
+        }
+        result[entry] = skillFile;
+    }
+    return result;
+}

package/dist/contentTransformer.d.ts

@@ -0,0 +1,16 @@
+import type { TargetId } from "./types.js";
+/**
+ * Transforms markdown content for selected AI target.
+ * @param input Original file content.
+ * @param target Target AI identifier.
+ * @param assetType Installed asset type.
+ * @returns Target-normalized markdown content.
+ */
+export declare function transformContentForTarget(input: string, target: TargetId, assetType: "orchestrator" | "agent" | "skill"): string;
+/**
+ * Returns whether markdown contains explicit hint for the selected target model.
+ * @param input Original markdown content.
+ * @param target Target AI identifier.
+ * @returns True when a native target hint is present.
+ */
+export declare function hasExplicitTargetHint(input: string, target: TargetId): boolean;

package/dist/contentTransformer.js

@@ -0,0 +1,195 @@
+const hintRegex = /<!--\s*(codex|claude|qwen|gemini)\s*:\s*([\s\S]*?)-->\s*\n?/gi;
+/**
+ * Transforms markdown content for selected AI target.
+ * @param input Original file content.
+ * @param target Target AI identifier.
+ * @param assetType Installed asset type.
+ * @returns Target-normalized markdown content.
+ */
+export function transformContentForTarget(input, target, assetType) {
+    const normalizedInput = stripBom(input).replace(/\r\n/g, "\n");
+    const parsedHints = [];
+    const foundHints = new Set();
+    const cleaned = normalizedInput.replace(hintRegex, (_match, model, payload) => {
+        const normalizedModel = String(model).toLowerCase();
+        foundHints.add(normalizedModel);
+        parsedHints.push({ model: normalizedModel, payload: String(payload).trim() });
+        return "";
+    });
+    const marker = buildMarker(target, assetType, [...foundHints]);
+    const mappedHint = buildMappedHint(target, parsedHints);
+    const output = cleaned.trimStart();
+    return `${marker}${mappedHint}${output.endsWith("\n") ? output : `${output}\n`}`;
+}
+/**
+ * Returns whether markdown contains explicit hint for the selected target model.
+ * @param input Original markdown content.
+ * @param target Target AI identifier.
+ * @returns True when a native target hint is present.
+ */
+export function hasExplicitTargetHint(input, target) {
+    const content = stripBom(input).replace(/\r\n/g, "\n");
+    const targetModel = targetToModel(target);
+    const hints = [...content.matchAll(/<!--\s*(codex|claude|qwen|gemini)\s*:\s*[\s\S]*?-->/gi)];
+    return hints.some((match) => String(match[1]).toLowerCase() === targetModel);
+}
+/**
+ * Returns content without UTF-8 BOM prefix.
+ * @param value Raw content.
+ * @returns BOM-free content.
+ */
+function stripBom(value) {
+    return value.charCodeAt(0) === 0xfeff ? value.slice(1) : value;
+}
+/**
+ * Builds target marker block for transformed files.
+ * @param target Target AI identifier.
+ * @param assetType Installed asset type.
+ * @param foundHints Removed model-specific hints.
+ * @returns Marker prefix.
+ */
+function buildMarker(target, assetType, foundHints) {
+    const hints = foundHints.length > 0 ? foundHints.join(",") : "none";
+    return `<!-- code-ai: target=${target}; asset=${assetType}; normalized_hints=${hints} -->\n`;
+}
+/**
+ * Builds target model hint from available source hints.
+ * @param target Target AI identifier.
+ * @param hints Parsed source hints.
+ * @returns Target-specific hint marker or empty string.
+ */
+function buildMappedHint(target, hints) {
+    const targetModel = targetToModel(target);
+    const native = hints.find((hint) => hint.model === targetModel);
+    if (native) {
+        return `<!-- ${targetModel}: ${native.payload} -->\n`;
+    }
+    const codex = hints.find((hint) => hint.model === "codex");
+    if (!codex) {
+        return "";
+    }
+    const mappedPayload = mapCodexPayload(codex.payload, targetModel);
+    return `<!-- ${targetModel}: ${mappedPayload} -->\n`;
+}
+/**
+ * Maps target id to hint model label.
+ * @param target Target AI identifier.
+ * @returns Target model name used in markdown hints.
+ */
+function targetToModel(target) {
+    if (target === "claude") {
+        return "claude";
+    }
+    if (target === "qwen-3.5") {
+        return "qwen";
+    }
+    if (target === "google-antugravity") {
+        return "gemini";
+    }
+    return "codex";
+}
+/**
+ * Converts codex hint payload to a target-model hint payload.
+ * @param payload Codex payload (for example: reasoning=high; note="..." ).
+ * @param targetModel Destination model.
+ * @returns Converted payload string.
+ */
+function mapCodexPayload(payload, targetModel) {
+    const reasoning = extractValue(payload, "reasoning");
+    const note = extractValue(payload, "note");
+    const normalizedReasoning = normalizeReasoning(reasoning);
+    if (targetModel === "claude") {
+        const thinking = mapReasoningToClaude(normalizedReasoning);
+        return withNote(`thinking=${thinking}`, note);
+    }
+    if (targetModel === "qwen") {
+        const effort = mapReasoningToQwen(normalizedReasoning);
+        return withNote(`reasoning_effort=${effort}`, note);
+    }
+    if (targetModel === "gemini") {
+        const effort = mapReasoningToGemini(normalizedReasoning);
+        return withNote(`reasoning=${effort}`, note);
+    }
+    return withNote(`reasoning=${normalizedReasoning}`, note);
+}
+/**
+ * Reads one key value from semicolon-separated payload.
+ * @param payload Input payload string.
+ * @param key Value key name.
+ * @returns Extracted value without quotes.
+ */
+function extractValue(payload, key) {
+    const pattern = new RegExp(`${key}\\s*=\\s*("([^"]*)"|[^;]+)`, "i");
+    const match = payload.match(pattern);
+    if (!match) {
+        return "";
+    }
+    const raw = match[2] ?? match[1] ?? "";
+    return raw.trim();
+}
+/**
+ * Normalizes codex reasoning aliases into low/medium/high/extra_high.
+ * @param value Raw reasoning value.
+ * @returns Normalized reasoning value.
+ */
+function normalizeReasoning(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "xhigh" || normalized === "very_high" || normalized === "extra-high") {
+        return "extra_high";
+    }
+    if (normalized === "extra_high") {
+        return "extra_high";
+    }
+    if (normalized === "high") {
+        return "high";
+    }
+    if (normalized === "low") {
+        return "low";
+    }
+    return "medium";
+}
+/**
+ * Maps normalized reasoning to Claude thinking levels.
+ * @param reasoning Normalized codex reasoning.
+ * @returns Claude thinking level.
+ */
+function mapReasoningToClaude(reasoning) {
+    if (reasoning === "extra_high") {
+        return "max";
+    }
+    return reasoning;
+}
+/**
+ * Maps normalized reasoning to Qwen effort levels.
+ * @param reasoning Normalized codex reasoning.
+ * @returns Qwen reasoning effort.
+ */
+function mapReasoningToQwen(reasoning) {
+    if (reasoning === "extra_high") {
+        return "high";
+    }
+    return reasoning;
+}
+/**
+ * Maps normalized reasoning to Gemini reasoning levels.
+ * @param reasoning Normalized codex reasoning.
+ * @returns Gemini reasoning level.
+ */
+function mapReasoningToGemini(reasoning) {
+    if (reasoning === "extra_high") {
+        return "high";
+    }
+    return reasoning;
+}
+/**
+ * Appends optional note to mapped hint payload.
+ * @param base Base payload.
+ * @param note Optional note value.
+ * @returns Payload with optional quoted note.
+ */
+function withNote(base, note) {
+    if (!note) {
+        return base;
+    }
+    return `${base}; note="${note}"`;
+}

package/dist/doctor.d.ts

@@ -0,0 +1,13 @@
+import type { TargetId } from "./types.js";
+/**
+ * Runs local diagnostics for source and destination readiness.
+ * @param projectDir Repository root.
+ * @param destinationDir Install destination.
+ * @param target Target id.
+ * @returns Diagnostic messages categorized by severity.
+ */
+export declare function runDoctor(projectDir: string, destinationDir: string, target: TargetId): Promise<{
+    errors: string[];
+    warnings: string[];
+    info: string[];
+}>;

package/dist/doctor.js

@@ -0,0 +1,37 @@
+import fs from "fs-extra";
+import { getPlatformAdapter } from "./platforms/adapters.js";
+import { loadSourceCatalog } from "./catalog.js";
+/**
+ * Runs local diagnostics for source and destination readiness.
+ * @param projectDir Repository root.
+ * @param destinationDir Install destination.
+ * @param target Target id.
+ * @returns Diagnostic messages categorized by severity.
+ */
+export async function runDoctor(projectDir, destinationDir, target) {
+    const errors = [];
+    const warnings = [];
+    const info = [];
+    try {
+        const catalog = await loadSourceCatalog(projectDir);
+        info.push(`Found ${Object.keys(catalog.agentFiles).length} agents.`);
+        info.push(`Found ${Object.keys(catalog.skillFiles).length} skills.`);
+    }
+    catch (error) {
+        errors.push(error.message);
+    }
+    const adapter = getPlatformAdapter(target);
+    warnings.push(...adapter.validateDestination(destinationDir));
+    try {
+        await fs.ensureDir(destinationDir);
+        const probeFile = `${destinationDir}/.code-ai-installer/.write-probe`;
+        await fs.ensureDir(`${destinationDir}/.code-ai-installer`);
+        await fs.writeFile(probeFile, "ok", "utf8");
+        await fs.remove(probeFile);
+        info.push("Destination is writable.");
+    }
+    catch (error) {
+        errors.push(`Destination is not writable: ${error.message}`);
+    }
+    return { errors, warnings, info };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};