codex-template 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-template contributors
+
+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,141 @@
+# codex-template
+
+[![CI](https://github.com/joeneldeasis/codex-template/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/joeneldeasis/codex-template/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/joeneldeasis/codex-template/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/joeneldeasis/codex-template/actions/workflows/codeql.yml)
+![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+Install [aitmpl.com](https://aitmpl.com/) skills, commands, agents, and MCPs into Codex.
+
+```bash
+npx codex-template --skill creative-design/frontend-design
+```
+
+## Installation
+
+```bash
+npm install -g codex-template
+codex-template --help
+```
+
+Or run it once without a global install:
+
+```bash
+npx codex-template@latest --skill creative-design/frontend-design
+```
+
+## Quick start
+
+Global install is the default. Add `--project` or `--directory <path>` to write into a repository.
+
+```bash
+npx codex-template --skill creative-design/frontend-design
+npx codex-template --command testing/generate-tests
+npx codex-template --agent development-team/frontend-developer
+npx codex-template --mcp web/web-fetch
+npx codex-template --doctor
+```
+
+| Component | Location |
+| --- | --- |
+| Skill | `~/.agents/skills/<name>/` |
+| Command | `~/.agents/skills/<name>/` as an explicit skill (`SKILL.md` plus `agents/openai.yaml`) |
+| Agent | `~/.codex/agents/<name>.toml` |
+| MCP | merged into `~/.codex/config.toml` as `[mcp_servers.<id>]` |
+
+The category prefix is dropped, so `creative-design/frontend-design` installs as `frontend-design`. Command text keeps `$ARGUMENTS` and Claude `!` syntax. The first write to `config.toml` also saves `config.toml.bak`.
+
+## Commands and options
+
+```text
+codex-template [options]
+
+--skill <ids>          Install skills, comma-separated
+--command <ids>        Install commands, comma-separated
+--agent <ids>          Install agents, comma-separated
+--mcp <ids>            Install MCPs, comma-separated
+-d, --directory <path> Install into a project instead of the user profile
+--project              Same as --directory .
+-y, --yes              Overwrite without prompting
+--dry-run              Show planned writes and do not change files
+--list [type]          List catalog ids
+--search <type> <query>
+--info <type> <id>
+--installed
+--remove <type> <id>
+--update <type> <id>
+--update --all
+--doctor
+--verbose
+--debug                Print stack traces
+-h, --help
+-V, --version
+```
+
+Browse the catalog at [skills](https://aitmpl.com/skills/), [commands](https://aitmpl.com/commands/), [agents](https://aitmpl.com/agents/), and [MCPs](https://aitmpl.com/mcps/).
+
+## Configuration
+
+There is no config file. Scope comes from the CLI:
+
+1. `--directory` or `--project` installs into that project
+2. otherwise files go under the user profile
+
+Existing keys in `config.toml`, including other MCP servers, are kept. A different value for the same server asks before overwrite unless `--yes` is set.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `GITHUB_TOKEN` | Optional token for the GitHub catalog API when unauthenticated requests are rate-limited. The token is not printed. |
+
+## Programmatic API
+
+```js
+import { installComponent, destRoots, createCatalog } from 'codex-template';
+
+const roots = destRoots({ target: 'codex', scope: 'project', directory: process.cwd() });
+const catalog = createCatalog();
+await installComponent({
+  target: 'codex',
+  roots,
+  type: 'skill',
+  id: 'creative-design/frontend-design',
+  yes: true,
+  catalog,
+});
+```
+
+Also exported: `removeComponent`, `listInstalled`, `checkInstall`, and `runCli`.
+
+## Troubleshooting
+
+`GitHub rate limit` means the catalog request was rejected. Set `GITHUB_TOKEN` and run the command again.
+
+`Unknown component type` means the type was not `skill`, `command`, `agent`, or `mcp`.
+
+`not found` means that catalog id is not in `davila7/claude-code-templates`. Check the id on aitmpl.com.
+
+Exit codes: `0` success, `1` the operation failed, `2` the arguments were invalid.
+
+## Development
+
+Requires Node.js 20 or newer.
+
+```bash
+npm ci
+npm run validate
+npm run ci
+```
+
+`npm run validate` lints, typechecks, builds `dist/`, tests, and writes coverage. `npm run ci` also checks the packed files and runs the tarball with npx from a clean temporary directory.
+
+## Publishing
+
+Publishing happens from a git tag `vX.Y.Z` whose version matches `package.json`. The release workflow runs the same validation, publishes with npm provenance, and creates a GitHub Release.
+
+The published package contains `dist/`, `bin/cli.js`, `README.md`, and `LICENSE`. Check a packed build locally with:
+
+```bash
+npm run ci
+```

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli/run.js';
+
+const code = await runCli('codex');
+process.exit(code);

package/dist/cli/args.d.ts

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import type { CliOptions, Target } from '../core/types.js';
+export declare function commandName(target: Target): string;
+export declare function buildProgram(target: Target): Command;
+export declare function expandArgv(argv: string[]): string[];
+interface RawOpts {
+    skill?: string;
+    command?: string;
+    agent?: string;
+    mcp?: string;
+    directory?: string;
+    project?: boolean;
+    yes?: boolean;
+    dryRun?: boolean;
+    verbose?: boolean;
+    debug?: boolean;
+    list?: string | boolean;
+    installed?: boolean;
+    doctor?: boolean;
+    search?: string;
+    info?: string;
+    remove?: string;
+    update?: string;
+    updateAll?: boolean;
+    all?: boolean;
+}
+export declare function optionsFromCommand(opts: RawOpts): CliOptions;
+export declare function parseCliArgs(argv: string[], target: Target): CliOptions;
+export declare function hasAction(options: CliOptions): boolean;
+export {};

package/dist/cli/args.js

@@ -0,0 +1,156 @@
+import { Command } from 'commander';
+import { VERSION } from '../config/constants.js';
+import { UsageError } from '../utils/errors.js';
+import { normalizeType, splitIds } from '../utils/ids.js';
+export function commandName(target) {
+    return target === 'cursor' ? 'cursor-template' : 'codex-template';
+}
+export function buildProgram(target) {
+    const name = commandName(target);
+    const program = new Command()
+        .name(name)
+        .description(`Install aitmpl.com skills, commands, agents, and MCPs for ${target === 'cursor' ? 'Cursor' : 'Codex'}`)
+        .version(VERSION)
+        .option('--skill <ids>', 'install skills (comma-separated)')
+        .option('--command <ids>', 'install commands (comma-separated)')
+        .option('--agent <ids>', 'install agents (comma-separated)')
+        .option('--mcp <ids>', 'install MCPs (comma-separated)')
+        .option('-d, --directory <path>', 'install into a project directory instead of the user profile')
+        .option('--project', 'alias for --directory .')
+        .option('-y, --yes', 'overwrite without prompting')
+        .option('--dry-run', 'show planned writes without changing files')
+        .option('--verbose', 'log catalog requests (tokens are not printed)')
+        .option('--debug', 'print stack traces for unexpected errors')
+        .option('--list [type]', 'list catalog ids (skill, command, agent, mcp)')
+        .option('--search <pair>', 'search the catalog: --search <type> <query>')
+        .option('--info <pair>', 'show one component: --info <type> <id>')
+        .option('--installed', 'list components on disk')
+        .option('--remove <pair>', 'remove one component: --remove <type> <id>')
+        .option('--update <pair>', 're-fetch one component: --update <type> <id>')
+        .option('--update-all', 're-fetch every installed component')
+        .option('--all', 'with --update, refresh everything installed')
+        .option('--doctor', 'check install directories and files')
+        .allowExcessArguments(false);
+    program.addHelpText('after', `
+Examples:
+  ${name} --skill creative-design/frontend-design
+  ${name} --command testing/generate-tests --project
+  ${name} --search skill frontend
+  ${name} --doctor
+
+Environment:
+  GITHUB_TOKEN    Optional GitHub token used when the catalog API is rate-limited
+`);
+    return program;
+}
+export function expandArgv(argv) {
+    const out = argv.slice(0, 2);
+    const args = argv.slice(2);
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === '--update' && args[i + 1] === '--all') {
+            out.push('--update-all');
+            i += 1;
+            continue;
+        }
+        if (token === '--update' && (!args[i + 1] || args[i + 1].startsWith('-'))) {
+            out.push('--update-all');
+            continue;
+        }
+        if (token === '--search' || token === '--info' || token === '--remove' || token === '--update') {
+            const left = args[i + 1];
+            const right = args[i + 2];
+            if (!left || left.startsWith('-') || !right || right.startsWith('-')) {
+                throw new UsageError(`${token} requires <type> and a second argument.\n\nUse:\n  ${token} skill creative-design/frontend-design`);
+            }
+            out.push(token, `${left} ${right}`);
+            i += 2;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+function splitPair(value, flag) {
+    const index = value.indexOf(' ');
+    if (index === -1)
+        throw new UsageError(`${flag} requires <type> and a second argument`);
+    return [value.slice(0, index), value.slice(index + 1)];
+}
+function listValue(value) {
+    if (typeof value !== 'string')
+        return value === true ? true : null;
+    return normalizeType(value);
+}
+export function optionsFromCommand(opts) {
+    const options = {
+        skill: splitIds(opts.skill),
+        command: splitIds(opts.command),
+        agent: splitIds(opts.agent),
+        mcp: splitIds(opts.mcp),
+        directory: opts.directory || null,
+        yes: Boolean(opts.yes),
+        dryRun: Boolean(opts.dryRun),
+        verbose: Boolean(opts.verbose),
+        debug: Boolean(opts.debug),
+        list: listValue(opts.list),
+        installed: Boolean(opts.installed),
+        doctor: Boolean(opts.doctor),
+        search: null,
+        info: null,
+        remove: null,
+        update: null,
+    };
+    if (opts.project && !options.directory)
+        options.directory = '.';
+    if (opts.search) {
+        const [type, query] = splitPair(opts.search, '--search');
+        options.search = { type: normalizeType(type), query };
+    }
+    if (opts.info) {
+        const [type, id] = splitPair(opts.info, '--info');
+        options.info = { type: normalizeType(type), id };
+    }
+    if (opts.remove) {
+        const [type, id] = splitPair(opts.remove, '--remove');
+        options.remove = { type: normalizeType(type), id };
+    }
+    if (opts.updateAll || opts.all)
+        options.update = { all: true };
+    else if (opts.update) {
+        const [type, id] = splitPair(opts.update, '--update');
+        options.update = { type: normalizeType(type), id };
+    }
+    if (opts.all && !opts.update && !opts.updateAll) {
+        throw new UsageError('Use --update --all to refresh every installed component.');
+    }
+    return options;
+}
+export function parseCliArgs(argv, target) {
+    const program = buildProgram(target);
+    program.exitOverride();
+    program.configureOutput({ writeOut: () => { }, writeErr: () => { } });
+    try {
+        program.parse(expandArgv(argv));
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(message);
+    }
+    return optionsFromCommand(program.opts());
+}
+export function hasAction(options) {
+    return Boolean(options.skill.length
+        || options.command.length
+        || options.agent.length
+        || options.mcp.length
+        || options.list !== null
+        || options.search
+        || options.info
+        || options.installed
+        || options.remove
+        || options.update
+        || options.doctor);
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,11 @@
+import type { Catalog, Target } from '../core/types.js';
+export interface CliIo {
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+    home?: string;
+    catalog?: Catalog;
+    fetchImpl?: typeof fetch;
+    argv?: string[];
+}
+export declare function printHelp(target: Target): void;
+export declare function runCli(target: Target, argv?: string[], io?: CliIo): Promise<number>;

package/dist/cli/run.js

@@ -0,0 +1,210 @@
+import os from 'node:os';
+import path from 'node:path';
+import chalk from 'chalk';
+import { BROWSE } from '../config/constants.js';
+import { doctor } from '../core/doctor.js';
+import { installById, removeInstalled, sourceLine } from '../core/install.js';
+import { collectInstalled } from '../core/lifecycle.js';
+import { readManifest } from '../core/manifest.js';
+import { componentDest, destRoots } from '../core/paths.js';
+import { createCatalog } from '../services/github.js';
+import { UsageError, formatError } from '../utils/errors.js';
+import { assertSafeId, normalizeType } from '../utils/ids.js';
+import { buildProgram, hasAction, parseCliArgs } from './args.js';
+function browseLines() {
+    return [
+        `  skills    ${BROWSE.skills}`,
+        `  commands  ${BROWSE.commands}`,
+        `  agents    ${BROWSE.agents}`,
+        `  mcps      ${BROWSE.mcps}`,
+    ].join('\n');
+}
+export function printHelp(target) {
+    buildProgram(target).outputHelp();
+    console.log(`\nBrowse:\n${browseLines()}`);
+}
+function rootsFor(target, options, home) {
+    return destRoots({
+        target,
+        scope: options.directory ? 'project' : 'global',
+        directory: options.directory ? path.resolve(options.directory) : undefined,
+        home,
+    });
+}
+export async function runCli(target, argv = process.argv, io = {}) {
+    const log = io.stdout || console.log;
+    const args = argv.slice(2);
+    if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+        printHelp(target);
+        return 0;
+    }
+    if (args.includes('-V') || args.includes('--version')) {
+        buildProgram(target).parse(argv);
+        return 0;
+    }
+    let options;
+    try {
+        options = parseCliArgs(argv, target);
+    }
+    catch (error) {
+        const stderr = io.stderr || ((message) => console.error(chalk.red(message)));
+        stderr(formatError(error, false));
+        return error instanceof UsageError ? error.exitCode : 2;
+    }
+    const stderr = io.stderr || ((message) => console.error(chalk.red(message)));
+    if (!hasAction(options)) {
+        printHelp(target);
+        return 0;
+    }
+    const roots = rootsFor(target, options, io.home || os.homedir());
+    const catalog = io.catalog || createCatalog({ verbose: options.verbose || options.debug, fetchImpl: io.fetchImpl });
+    let code = 0;
+    const fail = (error) => {
+        stderr(formatError(error, options.debug));
+        code = error instanceof UsageError ? error.exitCode : 1;
+    };
+    if (options.list !== null) {
+        try {
+            const records = await catalog.list(options.list === true ? null : options.list);
+            const groups = new Map();
+            for (const record of records) {
+                const list = groups.get(record.type) || [];
+                list.push(record.id);
+                groups.set(record.type, list);
+            }
+            for (const [group, ids] of groups) {
+                log(chalk.cyan(`${group} (${ids.length})`));
+                for (const id of ids)
+                    log(`  ${id}`);
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    if (options.search) {
+        try {
+            const records = await catalog.search(options.search.type, options.search.query);
+            if (!records.length)
+                log(`no ${options.search.type} matches for "${options.search.query}"`);
+            for (const record of records) {
+                const description = await catalog.descriptionFor(record);
+                log(`${record.id}${description ? `\n  ${description}` : ''}`);
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    if (options.info) {
+        try {
+            assertSafeId(options.info.id);
+            const record = await catalog.resolve(options.info.type, options.info.id);
+            const dest = componentDest({ target, roots, type: record.type, name: record.name });
+            const description = await catalog.descriptionFor(record);
+            log(`${record.type} ${record.id}`);
+            log(`name: ${record.name}`);
+            log(`source: ${sourceLine(record)}`);
+            log(`install: ${dest.path}`);
+            if (description)
+                log(`description: ${description}`);
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    if (options.installed) {
+        try {
+            const items = await collectInstalled({ target, roots });
+            if (!items.length)
+                log('nothing installed');
+            for (const item of items) {
+                const state = item.present ? '' : chalk.yellow(' missing');
+                log(`${item.type.padEnd(8)} ${item.tracked ? item.id : `${item.id} (untracked)`}${state}`);
+                log(`  ${item.path}`);
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    if (options.remove) {
+        try {
+            assertSafeId(options.remove.id);
+            const removed = await removeInstalled({
+                target,
+                roots,
+                type: options.remove.type,
+                id: options.remove.id,
+                yes: options.yes,
+                dryRun: options.dryRun,
+            });
+            if (!removed)
+                code = 1;
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    if (options.update) {
+        try {
+            const jobs = [];
+            if ('all' in options.update) {
+                const manifest = await readManifest(roots.manifest);
+                jobs.push(...Object.values(manifest.components));
+                if (!jobs.length)
+                    log('nothing installed to update');
+            }
+            else {
+                assertSafeId(options.update.id);
+                jobs.push({ type: options.update.type, id: options.update.id });
+            }
+            for (const job of jobs) {
+                const ok = await installById({
+                    target,
+                    roots,
+                    type: normalizeType(job.type),
+                    id: job.id,
+                    yes: true,
+                    dryRun: options.dryRun,
+                    catalog,
+                });
+                if (ok === false)
+                    code = 1;
+            }
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    for (const type of ['skill', 'command', 'agent', 'mcp']) {
+        for (const id of options[type]) {
+            try {
+                assertSafeId(id);
+                const ok = await installById({ target, roots, type, id, yes: options.yes, dryRun: options.dryRun, catalog });
+                if (ok === false)
+                    code = 1;
+            }
+            catch (error) {
+                fail(error);
+            }
+        }
+    }
+    if (options.doctor) {
+        try {
+            const report = await doctor({ target, roots });
+            for (const note of report.notes)
+                log(chalk.green(note));
+            for (const issue of report.issues)
+                log(chalk.yellow(issue));
+            if (report.issues.length)
+                code = 1;
+            else if (!report.notes.length)
+                log('doctor: ok');
+        }
+        catch (error) {
+            fail(error);
+        }
+    }
+    return code;
+}

package/dist/config/constants.d.ts

@@ -0,0 +1,27 @@
+export declare const REPO = "davila7/claude-code-templates";
+export declare const BRANCH = "main";
+export declare const COMPONENTS_PREFIX = "cli-tool/components/";
+export declare const VERSION = "0.1.0";
+export declare const USER_AGENT = "cursor-codex-templates/0.1.0";
+export declare const BROWSE: {
+    readonly skills: "https://aitmpl.com/skills/";
+    readonly commands: "https://aitmpl.com/commands/";
+    readonly agents: "https://aitmpl.com/agents/";
+    readonly mcps: "https://aitmpl.com/mcps/";
+};
+export declare const TYPE_ALIASES: {
+    readonly skill: "skill";
+    readonly skills: "skill";
+    readonly command: "command";
+    readonly commands: "command";
+    readonly agent: "agent";
+    readonly agents: "agent";
+    readonly mcp: "mcp";
+    readonly mcps: "mcp";
+};
+export declare const CATALOG_GROUPS: {
+    readonly skills: "skill";
+    readonly commands: "command";
+    readonly agents: "agent";
+    readonly mcps: "mcp";
+};

package/dist/config/constants.js

@@ -0,0 +1,27 @@
+export const REPO = 'davila7/claude-code-templates';
+export const BRANCH = 'main';
+export const COMPONENTS_PREFIX = 'cli-tool/components/';
+export const VERSION = '0.1.0';
+export const USER_AGENT = `cursor-codex-templates/${VERSION}`;
+export const BROWSE = {
+    skills: 'https://aitmpl.com/skills/',
+    commands: 'https://aitmpl.com/commands/',
+    agents: 'https://aitmpl.com/agents/',
+    mcps: 'https://aitmpl.com/mcps/',
+};
+export const TYPE_ALIASES = {
+    skill: 'skill',
+    skills: 'skill',
+    command: 'command',
+    commands: 'command',
+    agent: 'agent',
+    agents: 'agent',
+    mcp: 'mcp',
+    mcps: 'mcp',
+};
+export const CATALOG_GROUPS = {
+    skills: 'skill',
+    commands: 'command',
+    agents: 'agent',
+    mcps: 'mcp',
+};

package/dist/core/adapters.d.ts

@@ -0,0 +1,7 @@
+export declare function cursorAgentMarkdown(markdown: string): string;
+export declare function agentMarkdownToToml(markdown: string, fallbackName: string): string;
+export declare function wrapCommandAsSkill(markdown: string, name: string): {
+    skill: string;
+    openaiYaml: string;
+    description: string;
+};

package/dist/core/adapters.js

@@ -0,0 +1,28 @@
+import { stringify } from 'smol-toml';
+import { descriptionText, parseFrontmatter, stringifyFrontmatter } from '../utils/frontmatter.js';
+export function cursorAgentMarkdown(markdown) {
+    const { data, body } = parseFrontmatter(markdown);
+    if (!Object.keys(data).length)
+        return markdown.endsWith('\n') ? markdown : `${markdown}\n`;
+    delete data.tools;
+    return stringifyFrontmatter(data, body);
+}
+export function agentMarkdownToToml(markdown, fallbackName) {
+    const { data, body } = parseFrontmatter(markdown);
+    const name = descriptionText(data.name) || fallbackName;
+    const description = descriptionText(data.description) || `Use the ${name} agent.`;
+    return stringify({
+        name,
+        description,
+        developer_instructions: `${body.trim()}\n`,
+    });
+}
+export function wrapCommandAsSkill(markdown, name) {
+    const { data, body } = parseFrontmatter(markdown);
+    const description = descriptionText(data.description) || `Run the ${name} workflow from aitmpl.`;
+    return {
+        skill: stringifyFrontmatter({ name, description }, body),
+        openaiYaml: 'policy:\n  allow_implicit_invocation: false\n',
+        description,
+    };
+}

package/dist/core/doctor.d.ts

@@ -0,0 +1,8 @@
+import type { InstallRoots, Target } from './types.js';
+export declare function doctor({ target, roots }: {
+    target: Target;
+    roots: InstallRoots;
+}): Promise<{
+    issues: string[];
+    notes: string[];
+}>;