codex-template 0.1.0

package/dist/core/paths.js

@@ -0,0 +1,54 @@
+import os from 'node:os';
+import path from 'node:path';
+export function destRoots({ target, scope = 'global', directory, home = os.homedir(), }) {
+    if (target !== 'cursor' && target !== 'codex') {
+        throw new Error(`Unknown target "${target}"`);
+    }
+    const project = scope === 'project';
+    if (project && !directory) {
+        throw new Error('Project installs require a directory');
+    }
+    const projectRoot = project ? path.resolve(directory) : null;
+    if (target === 'cursor') {
+        const base = project ? path.join(projectRoot, '.cursor') : path.join(home, '.cursor');
+        return {
+            target,
+            scope: project ? 'project' : 'global',
+            base,
+            skills: path.join(base, 'skills'),
+            commands: path.join(base, 'commands'),
+            agents: path.join(base, 'agents'),
+            mcpFile: path.join(base, 'mcp.json'),
+            manifest: path.join(base, '.aitmpl-manifest.json'),
+        };
+    }
+    const base = project ? path.join(projectRoot, '.codex') : path.join(home, '.codex');
+    const skills = project
+        ? path.join(projectRoot, '.agents', 'skills')
+        : path.join(home, '.agents', 'skills');
+    return {
+        target,
+        scope: project ? 'project' : 'global',
+        base,
+        skills,
+        commands: skills,
+        agents: path.join(base, 'agents'),
+        mcpFile: path.join(base, 'config.toml'),
+        manifest: path.join(base, '.aitmpl-manifest.json'),
+    };
+}
+export function componentDest({ target, roots, type, name, }) {
+    if (type === 'skill')
+        return { kind: 'dir', path: path.join(roots.skills, name) };
+    if (type === 'command' && target === 'cursor')
+        return { kind: 'file', path: path.join(roots.commands, `${name}.md`) };
+    if (type === 'command' && target === 'codex')
+        return { kind: 'dir', path: path.join(roots.commands, name) };
+    if (type === 'agent' && target === 'cursor')
+        return { kind: 'file', path: path.join(roots.agents, `${name}.md`) };
+    if (type === 'agent' && target === 'codex')
+        return { kind: 'file', path: path.join(roots.agents, `${name}.toml`) };
+    if (type === 'mcp')
+        return { kind: 'merge', path: roots.mcpFile };
+    throw new Error(`Unknown component type "${type}"`);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,80 @@
+export type Target = 'cursor' | 'codex';
+export type ComponentType = 'skill' | 'command' | 'agent' | 'mcp';
+export type Scope = 'global' | 'project';
+export interface SkillFile {
+    repoPath: string;
+    rel: string;
+}
+export interface ComponentRecord {
+    type: ComponentType;
+    id: string;
+    name: string;
+    category: string;
+    repoPath?: string;
+    repoDir?: string;
+    primaryPath: string;
+    files: SkillFile[];
+}
+export interface InstallRoots {
+    target: Target;
+    scope: Scope;
+    base: string;
+    skills: string;
+    commands: string;
+    agents: string;
+    mcpFile: string;
+    manifest: string;
+}
+export interface Dest {
+    kind: 'dir' | 'file' | 'merge';
+    path: string;
+}
+export interface ManifestEntry {
+    type: ComponentType;
+    id: string;
+    name: string;
+    mcpServers: string[];
+}
+export interface Manifest {
+    version: 1;
+    components: Record<string, ManifestEntry>;
+}
+export interface Catalog {
+    resolve(type: ComponentType, id: string): Promise<ComponentRecord>;
+    list(type?: ComponentType | null): Promise<ComponentRecord[]>;
+    search(type: ComponentType, query: string): Promise<ComponentRecord[]>;
+    descriptionFor(record: ComponentRecord): Promise<string>;
+    readFile(repoPath: string): Promise<Buffer | null>;
+}
+export interface CliOptions {
+    skill: string[];
+    command: string[];
+    agent: string[];
+    mcp: string[];
+    directory: string | null;
+    yes: boolean;
+    dryRun: boolean;
+    verbose: boolean;
+    debug: boolean;
+    list: true | ComponentType | null;
+    installed: boolean;
+    doctor: boolean;
+    search: {
+        type: ComponentType;
+        query: string;
+    } | null;
+    info: {
+        type: ComponentType;
+        id: string;
+    } | null;
+    remove: {
+        type: ComponentType;
+        id: string;
+    } | null;
+    update: {
+        all: true;
+    } | {
+        type: ComponentType;
+        id: string;
+    } | null;
+}

package/dist/core/types.js

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { runCli } from './cli/run.js';
+export { installById as installComponent, removeInstalled as removeComponent } from './core/install.js';
+export { collectInstalled as listInstalled } from './core/lifecycle.js';
+export { doctor as checkInstall } from './core/doctor.js';
+export { destRoots } from './core/paths.js';
+export { createCatalog } from './services/github.js';
+export type { Target, ComponentType, Catalog, CliOptions, InstallRoots } from './core/types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { runCli } from './cli/run.js';
+export { installById as installComponent, removeInstalled as removeComponent } from './core/install.js';
+export { collectInstalled as listInstalled } from './core/lifecycle.js';
+export { doctor as checkInstall } from './core/doctor.js';
+export { destRoots } from './core/paths.js';
+export { createCatalog } from './services/github.js';

package/dist/services/github.d.ts

@@ -0,0 +1,28 @@
+import type { Catalog, ComponentRecord, ComponentType } from '../core/types.js';
+interface TreeEntry {
+    type?: string;
+    path?: string;
+}
+interface CatalogIndex {
+    skill: Map<string, ComponentRecord>;
+    command: Map<string, ComponentRecord>;
+    agent: Map<string, ComponentRecord>;
+    mcp: Map<string, ComponentRecord>;
+    skillByName: Map<string, ComponentRecord[]>;
+    commandByName: Map<string, ComponentRecord[]>;
+    agentByName: Map<string, ComponentRecord[]>;
+    mcpByName: Map<string, ComponentRecord[]>;
+}
+export declare function rawUrl(repoPath: string): string;
+export declare function githubBlobUrl(repoPath: string): string;
+export declare function indexFromTree(tree: TreeEntry[]): CatalogIndex;
+export declare function resolveFromIndex(index: CatalogIndex, type: ComponentType, id: string): ComponentRecord;
+export declare function listFromIndex(index: CatalogIndex, type?: ComponentType | null): ComponentRecord[];
+export declare function filterRecords(records: ComponentRecord[], query: string, descriptions?: Map<string, string>): ComponentRecord[];
+export declare function descriptionsFromCatalog(json: unknown): Map<string, string>;
+export declare function createCatalog({ fetchImpl, token, verbose, }?: {
+    fetchImpl?: typeof fetch;
+    token?: string;
+    verbose?: boolean;
+}): Catalog;
+export {};

package/dist/services/github.js

@@ -0,0 +1,211 @@
+import { BRANCH, CATALOG_GROUPS, COMPONENTS_PREFIX, REPO, USER_AGENT } from '../config/constants.js';
+import { catalogId } from '../utils/ids.js';
+export function rawUrl(repoPath) {
+    return `https://raw.githubusercontent.com/${REPO}/${BRANCH}/${repoPath}`;
+}
+export function githubBlobUrl(repoPath) {
+    return `https://github.com/${REPO}/blob/${BRANCH}/${repoPath}`;
+}
+export function indexFromTree(tree) {
+    const index = {
+        skill: new Map(),
+        command: new Map(),
+        agent: new Map(),
+        mcp: new Map(),
+        skillByName: new Map(),
+        commandByName: new Map(),
+        agentByName: new Map(),
+        mcpByName: new Map(),
+    };
+    const skillFiles = new Map();
+    for (const entry of tree) {
+        if (!entry || entry.type !== 'blob' || typeof entry.path !== 'string')
+            continue;
+        if (!entry.path.startsWith(COMPONENTS_PREFIX))
+            continue;
+        const rest = entry.path.slice(COMPONENTS_PREFIX.length);
+        const parts = rest.split('/');
+        const kind = parts[0];
+        if (kind === 'skills' && parts.length >= 3) {
+            const category = parts[1];
+            const name = parts[2];
+            const rel = parts.slice(3).join('/');
+            if (!rel || rel.split('/').includes('..'))
+                continue;
+            const id = catalogId(category, name);
+            if (!skillFiles.has(id)) {
+                skillFiles.set(id, {
+                    type: 'skill',
+                    id,
+                    name,
+                    category,
+                    repoDir: `${COMPONENTS_PREFIX}skills/${category}/${name}`,
+                    primaryPath: `${COMPONENTS_PREFIX}skills/${category}/${name}/SKILL.md`,
+                    files: [],
+                });
+            }
+            skillFiles.get(id)?.files.push({ repoPath: entry.path, rel });
+            continue;
+        }
+        if (parts.length !== 3)
+            continue;
+        const category = parts[1];
+        const file = parts[2];
+        if (kind === 'commands' && file.endsWith('.md'))
+            addFlat(index, 'command', category, file.replace(/\.md$/, ''), entry.path);
+        else if (kind === 'agents' && file.endsWith('.md'))
+            addFlat(index, 'agent', category, file.replace(/\.md$/, ''), entry.path);
+        else if (kind === 'mcps' && file.endsWith('.json'))
+            addFlat(index, 'mcp', category, file.replace(/\.json$/, ''), entry.path);
+    }
+    for (const record of skillFiles.values()) {
+        record.files.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+        index.skill.set(record.id, record);
+        pushName(index.skillByName, record);
+    }
+    return index;
+}
+function addFlat(index, type, category, name, repoPath) {
+    const record = {
+        type,
+        id: catalogId(category, name),
+        name,
+        category,
+        repoPath,
+        primaryPath: repoPath,
+        files: [{ repoPath, rel: repoPath.split('/').pop() || name }],
+    };
+    index[type].set(record.id, record);
+    pushName(index[`${type}ByName`], record);
+}
+function pushName(map, record) {
+    const list = map.get(record.name) || [];
+    list.push(record);
+    map.set(record.name, list);
+}
+function label(type) {
+    if (type === 'mcp')
+        return 'MCP';
+    return type.charAt(0).toUpperCase() + type.slice(1);
+}
+export function resolveFromIndex(index, type, id) {
+    const map = index[type];
+    if (String(id).includes('/')) {
+        const hit = map.get(id);
+        if (!hit) {
+            const error = new Error(`${label(type)} "${id}" not found`);
+            throw error;
+        }
+        return hit;
+    }
+    const matches = index[`${type}ByName`].get(id) || [];
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length === 0)
+        throw new Error(`${label(type)} "${id}" not found`);
+    throw new Error(`${label(type)} "${id}" is ambiguous: ${matches.map((item) => item.id).sort().join(', ')}`);
+}
+export function listFromIndex(index, type) {
+    if (type)
+        return [...index[type].values()].sort((a, b) => a.id.localeCompare(b.id));
+    return ['skill', 'command', 'agent', 'mcp'].flatMap((key) => listFromIndex(index, key));
+}
+export function filterRecords(records, query, descriptions = new Map()) {
+    const needle = String(query || '').trim().toLowerCase();
+    if (!needle)
+        return records;
+    return records.filter((record) => {
+        const description = descriptions.get(`${record.type}:${record.id}`) || '';
+        return [record.id, record.name, record.category, description].join('\n').toLowerCase().includes(needle);
+    });
+}
+export function descriptionsFromCatalog(json) {
+    const map = new Map();
+    if (!json || typeof json !== 'object')
+        return map;
+    const record = json;
+    for (const [group, type] of Object.entries(CATALOG_GROUPS)) {
+        const items = record[group];
+        if (!Array.isArray(items))
+            continue;
+        for (const item of items) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const entry = item;
+            const id = String(entry.path || '').replace(/\\/g, '/').replace(/\.(md|json)$/i, '');
+            if (!id)
+                continue;
+            map.set(`${type}:${id}`, typeof entry.description === 'string' ? entry.description.trim() : '');
+        }
+    }
+    return map;
+}
+export function createCatalog({ fetchImpl = globalThis.fetch, token = process.env.GITHUB_TOKEN, verbose = false, } = {}) {
+    let treePromise;
+    let descriptionPromise;
+    function log(message) {
+        if (verbose)
+            console.error(message);
+    }
+    async function github(url, accept) {
+        const headers = { 'User-Agent': USER_AGENT, Accept: accept };
+        if (token)
+            headers.Authorization = `Bearer ${token}`;
+        log(`GET ${url}`);
+        const response = await fetchImpl(url, { headers });
+        if (response.status === 403 || response.status === 429) {
+            throw new Error(`GitHub rate limit (${response.status}). Set GITHUB_TOKEN and retry.`);
+        }
+        return response;
+    }
+    async function getTree() {
+        if (!treePromise) {
+            treePromise = (async () => {
+                const response = await github(`https://api.github.com/repos/${REPO}/git/trees/${BRANCH}?recursive=1`, 'application/vnd.github+json');
+                if (!response.ok)
+                    throw new Error(`GitHub tree fetch failed: HTTP ${response.status}`);
+                const data = await response.json();
+                if (data.truncated)
+                    throw new Error('GitHub tree response was truncated. Set GITHUB_TOKEN and retry.');
+                return indexFromTree(data.tree || []);
+            })();
+        }
+        return treePromise;
+    }
+    async function descriptions() {
+        if (!descriptionPromise) {
+            descriptionPromise = (async () => {
+                const response = await github(rawUrl('docs/components.json'), 'application/octet-stream');
+                if (!response.ok)
+                    return new Map();
+                return descriptionsFromCatalog(await response.json());
+            })().catch((error) => {
+                log(`description index unavailable: ${error instanceof Error ? error.message : error}`);
+                return new Map();
+            });
+        }
+        return descriptionPromise;
+    }
+    return {
+        async resolve(type, id) {
+            return resolveFromIndex(await getTree(), type, id);
+        },
+        async list(type) {
+            return listFromIndex(await getTree(), type);
+        },
+        async search(type, query) {
+            return filterRecords(listFromIndex(await getTree(), type), query, await descriptions());
+        },
+        async descriptionFor(record) {
+            return (await descriptions()).get(`${record.type}:${record.id}`) || '';
+        },
+        async readFile(repoPath) {
+            const response = await github(rawUrl(repoPath), 'application/octet-stream');
+            if (response.status === 404)
+                return null;
+            if (!response.ok)
+                throw new Error(`Download failed for ${repoPath}: HTTP ${response.status}`);
+            return Buffer.from(await response.arrayBuffer());
+        },
+    };
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class UsageError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export declare function errorMessage(error: unknown): string;
+export declare function formatError(error: unknown, debug: boolean): string;

package/dist/utils/errors.js

@@ -0,0 +1,17 @@
+export class UsageError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+export function formatError(error, debug) {
+    if (debug && error instanceof Error && error.stack)
+        return error.stack;
+    return errorMessage(error);
+}

package/dist/utils/frontmatter.d.ts

@@ -0,0 +1,6 @@
+export declare function parseFrontmatter(text: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+export declare function stringifyFrontmatter(data: Record<string, unknown>, body: string): string;
+export declare function descriptionText(value: unknown): string;

package/dist/utils/frontmatter.js

@@ -0,0 +1,32 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+export function parseFrontmatter(text) {
+    const src = String(text).replace(/^\uFEFF/, '');
+    if (!src.startsWith('---'))
+        return { data: {}, body: src };
+    const match = src.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return { data: {}, body: src };
+    let data = {};
+    try {
+        const parsed = parseYaml(match[1] ?? '');
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            data = parsed;
+        }
+    }
+    catch {
+        data = {};
+    }
+    return { data, body: src.slice(match[0].length) };
+}
+export function stringifyFrontmatter(data, body) {
+    const yaml = stringifyYaml(data).trimEnd();
+    const rest = String(body || '').replace(/^\n/, '');
+    return `---\n${yaml}\n---\n\n${rest.trim()}\n`;
+}
+export function descriptionText(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (value == null)
+        return '';
+    return String(value).trim();
+}

package/dist/utils/fs.d.ts

@@ -0,0 +1,19 @@
+import type { Readable, Writable } from 'node:stream';
+export declare function pathExists(file: string): Promise<boolean>;
+export declare function safeJoin(root: string, rel: string): string;
+export declare function writeBytes(file: string, data: string | Buffer, { executable, dryRun }?: {
+    executable?: boolean;
+    dryRun?: boolean;
+}): Promise<void>;
+export declare function isExecutableRel(rel: string): boolean;
+export declare function confirm(question: string, { yes, dryRun, input, output, }?: {
+    yes?: boolean;
+    dryRun?: boolean;
+    input?: Readable;
+    output?: Writable;
+}): Promise<boolean>;
+export declare function nearestExistingParent(file: string): Promise<string>;
+export declare function isWritableDir(dir: string): Promise<boolean>;
+export declare function listChildDirs(dir: string): Promise<string[]>;
+export declare function listChildFiles(dir: string, extension?: string): Promise<string[]>;
+export declare function backupOnce(file: string): Promise<void>;

package/dist/utils/fs.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+function isEnoent(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+export async function pathExists(file) {
+    try {
+        await fs.access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function safeJoin(root, rel) {
+    if (!rel || rel.split('/').includes('..')) {
+        throw new Error(`Refusing unsafe relative path "${rel}".`);
+    }
+    const dest = path.resolve(root, rel);
+    const base = path.resolve(root);
+    if (dest !== base && !dest.startsWith(base + path.sep)) {
+        throw new Error(`Refusing to write outside ${base}: ${rel}`);
+    }
+    return dest;
+}
+export async function writeBytes(file, data, { executable = false, dryRun = false } = {}) {
+    if (dryRun) {
+        console.log(`would write ${file}`);
+        return;
+    }
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, data);
+    if (executable)
+        await fs.chmod(file, 0o755);
+}
+export function isExecutableRel(rel) {
+    return rel.endsWith('.py') || rel.endsWith('.sh');
+}
+export async function confirm(question, { yes = false, dryRun = false, input = process.stdin, output = process.stdout, } = {}) {
+    if (yes || dryRun)
+        return true;
+    if (!('isTTY' in input) || !input.isTTY) {
+        console.log('skipped (not a TTY; pass --yes to overwrite)');
+        return false;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question(question);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function nearestExistingParent(file) {
+    let current = file;
+    for (;;) {
+        if (await pathExists(current))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+}
+export async function isWritableDir(dir) {
+    const existing = await nearestExistingParent(dir);
+    try {
+        await fs.access(existing, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function listChildDirs(dir) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(dir, entry.name));
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+}
+export async function listChildFiles(dir, extension) {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && (!extension || entry.name.endsWith(extension)))
+            .map((entry) => path.join(dir, entry.name));
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return [];
+        throw error;
+    }
+}
+export async function backupOnce(file) {
+    const backup = `${file}.bak`;
+    if (!(await pathExists(file)) || (await pathExists(backup)))
+        return;
+    await fs.copyFile(file, backup);
+}

package/dist/utils/ids.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentType } from '../core/types.js';
+export declare function splitIds(value: string | undefined): string[];
+export declare function baseName(id: string): string;
+export declare function normalizeType(type: string): ComponentType;
+export declare function catalogId(category: string, name: string): string;
+export declare function assertSafeId(id: string): void;

package/dist/utils/ids.js

@@ -0,0 +1,30 @@
+import { TYPE_ALIASES } from '../config/constants.js';
+import { UsageError } from './errors.js';
+export function splitIds(value) {
+    if (!value)
+        return [];
+    return String(value)
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+export function baseName(id) {
+    const parts = String(id).split('/').filter(Boolean);
+    return parts[parts.length - 1] || '';
+}
+export function normalizeType(type) {
+    const key = String(type || '').trim().toLowerCase();
+    const normalized = TYPE_ALIASES[key];
+    if (!normalized) {
+        throw new UsageError(`Unknown component type "${type}". Use skill, command, agent, or mcp.`);
+    }
+    return normalized;
+}
+export function catalogId(category, name) {
+    return `${category}/${name}`;
+}
+export function assertSafeId(id) {
+    if (!id || id.includes('..') || id.includes('\\') || id.startsWith('/') || id.includes('\0')) {
+        throw new UsageError(`Invalid component id "${id}". Use a catalog id such as creative-design/frontend-design.`);
+    }
+}