@3xhaust/oh-my-design 0.16.1

package/adapters/build.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse } from 'yaml';
+import { emitCodex } from './codex.ts';
+import { emitClaude, emitClaudePlugin, pluginizeSkill } from './claude.ts';
+import { substituter } from './tokens.ts';
+import type { AbstractAgent, Emitted, Host } from '../core/types.ts';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function readAll<T>(dir: string, ext: string, parseOne: (text: string) => T): T[] {
+  const path = join(root, dir);
+  if (!existsSync(path)) return [];
+  return readdirSync(path)
+    .filter((f) => f.endsWith(ext))
+    .map((f) => parseOne(readFileSync(join(path, f), 'utf8')));
+}
+
+interface Skill {
+  name: string;
+  description: string;
+  source: string;
+}
+
+function readSkills(): Skill[] {
+  const dir = join(root, 'src', 'skills');
+  if (!existsSync(dir)) return [];
+  const skills: Skill[] = [];
+  for (const name of readdirSync(dir)) {
+    const file = join(dir, name, 'SKILL.md');
+    if (!existsSync(file)) continue;
+    const source = readFileSync(file, 'utf8');
+    const match = /^---\n([\s\S]*?)\n---/.exec(source);
+    const frontmatter = (match?.[1] ? parse(match[1]) : {}) as { name?: string; description?: string };
+    skills.push({ name: frontmatter.name ?? name, description: frontmatter.description ?? '', source });
+  }
+  return skills;
+}
+
+const firstSentence = (s: string): string => (/^[^.。]*[.。]?/.exec(s.trim())?.[0] ?? '').trim();
+const titleCase = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
+export const skillDisplayName = (name: string): string => name.startsWith('omd-') ? `(omd) ${name.slice(4)}` : titleCase(name);
+
+export const skillOpenaiMetadata = (name: string, description: string): string => [
+  'interface:',
+  `  display_name: ${JSON.stringify(skillDisplayName(name))}`,
+  `  short_description: ${JSON.stringify(firstSentence(description))}`,
+  '',
+].join('\n');
+
+function write(host: Host, rel: string, content: unknown): void {
+  const path = join(root, 'dist', host, rel);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, typeof content === 'string' ? content : `${JSON.stringify(content, null, 2)}\n`);
+}
+
+export function build(): void {
+  // Wipe first. A file that stopped being emitted must stop being installed — a stale
+  // hooks/ directory left here is a gate that quietly comes back to life.
+  rmSync(join(root, 'dist'), { recursive: true, force: true });
+
+  const agents = readAll<AbstractAgent>('src/agents', '.agent.yaml', (t) => parse(t) as AbstractAgent);
+  const skills = readSkills();
+
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version: string };
+
+  const emitters: Record<Host, (opts: { agents: AbstractAgent[] }) => Emitted> = {
+    codex: (opts) => emitCodex({ ...opts, version: pkg.version }),
+    claude: emitClaude,
+  };
+
+  for (const host of Object.keys(emitters) as Host[]) {
+    const { files } = emitters[host]({ agents });
+    for (const [rel, content] of Object.entries(files)) write(host, rel, content);
+
+    const sub = substituter(host);
+    for (const skill of skills) {
+      write(host, `skills/${skill.name}/SKILL.md`, sub(skill.source));
+      if (host === 'codex') {
+        write(host, `skills/${skill.name}/agents/openai.yaml`, skillOpenaiMetadata(skill.name, skill.description));
+      }
+    }
+
+    // Copy theory pack so agents can read it via `omd pack dir` + /theory/
+    const theoryDir = join(root, 'core', 'theory');
+    if (existsSync(theoryDir)) {
+      for (const f of readdirSync(theoryDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/theory/${f}`, readFileSync(join(theoryDir, f), 'utf8'));
+      }
+    }
+
+    // Copy motion pack (easing vocabulary + recipe cookbook) so agents can read it
+    // via `omd pack dir` + /motion/ and /motion/recipes/
+    const motionDir = join(root, 'core', 'motion');
+    if (existsSync(motionDir)) {
+      for (const f of readdirSync(motionDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/motion/${f}`, readFileSync(join(motionDir, f), 'utf8'));
+      }
+      const recipesDir = join(motionDir, 'recipes');
+      if (existsSync(recipesDir)) {
+        for (const f of readdirSync(recipesDir).filter((f) => f.endsWith('.md'))) {
+          write(host, `core/motion/recipes/${f}`, readFileSync(join(recipesDir, f), 'utf8'));
+        }
+      }
+    }
+
+    // Copy composition pack (page-level composition recipes) so agents can read it
+    // via `omd pack dir` + /composition/
+    const compositionDir = join(root, 'core', 'composition');
+    if (existsSync(compositionDir)) {
+      for (const f of readdirSync(compositionDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/composition/${f}`, readFileSync(join(compositionDir, f), 'utf8'));
+      }
+    }
+
+    // Copy graphics pack (background and image treatment recipes) so agents can read it
+    // via `omd pack dir` + /graphics/
+    const graphicsDir = join(root, 'core', 'graphics');
+    if (existsSync(graphicsDir)) {
+      for (const f of readdirSync(graphicsDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/graphics/${f}`, readFileSync(join(graphicsDir, f), 'utf8'));
+      }
+    }
+
+    // Copy craft pack (finish-pass checklist and related craft material) so agents can read it
+    // via `omd pack dir` + /craft/
+    const craftDir = join(root, 'core', 'craft');
+    if (existsSync(craftDir)) {
+      for (const f of readdirSync(craftDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/craft/${f}`, readFileSync(join(craftDir, f), 'utf8'));
+      }
+    }
+
+    // Copy the host-neutral loop contract alongside the theory/cookbook packs.
+    const protocolDir = join(root, 'core', 'protocol');
+    if (existsSync(protocolDir)) {
+      for (const f of readdirSync(protocolDir).filter((f) => f.endsWith('.md'))) {
+        write(host, `core/protocol/${f}`, readFileSync(join(protocolDir, f), 'utf8'));
+      }
+    }
+
+    console.log(`${host}: ${Object.keys(files).length} files, ${skills.length} skills`);
+  }
+
+  emitPlugin(agents, skills);
+}
+
+/**
+ * The marketplace flavor: written to <root>/skills, <root>/agents, <root>/.mcp.json —
+ * NOT dist/. This is what a marketplace install of the "omd" plugin actually loads, so
+ * unlike dist/ it must be committed. `join(root, 'skills')` is deliberately distinct from
+ * `join(root, 'src', 'skills')` (the source of truth, read by readSkills above) — this
+ * function must never wipe or write under src/.
+ */
+function emitPlugin(agents: AbstractAgent[], skills: Skill[]): void {
+  for (const dir of ['skills', 'agents']) rmSync(join(root, dir), { recursive: true, force: true });
+  rmSync(join(root, '.mcp.json'), { force: true });
+
+  const pluginized = skills.map((skill) => pluginizeSkill(skill.source));
+  for (let i = 0; i < pluginized.length; i += 1) {
+    const { name, source } = pluginized[i]!;
+    const canonical = skills[i]!;
+    const path = join(root, 'skills', name, 'SKILL.md');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, source);
+    const metadataPath = join(root, 'skills', name, 'agents', 'openai.yaml');
+    mkdirSync(dirname(metadataPath), { recursive: true });
+    writeFileSync(metadataPath, skillOpenaiMetadata(canonical.name, canonical.description));
+  }
+
+  const { files } = emitClaudePlugin({ agents });
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(root, rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, typeof content === 'string' ? content : `${JSON.stringify(content, null, 2)}\n`);
+  }
+
+  console.log(`plugin (root): ${pluginized.length} skills, ${agents.length} agents`);
+}
+
+// Run when invoked directly (`node adapters/build.ts`), not when imported by install.ts.
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) build();

package/adapters/claude.ts

@@ -0,0 +1,111 @@
+import { substituter } from './tokens.ts';
+import type { AbstractAgent, Emitted } from '../core/types.ts';
+
+const substitute = substituter('claude');
+
+// Published server, not one we run: gives the model eyes (navigate/screenshot) without
+// us hosting anything. Our own deterministic measurement stays in the `omd` CLI.
+const MCP_SERVERS = {
+  mcpServers: {
+    'chrome-devtools': {
+      command: 'npx',
+      args: ['-y', 'chrome-devtools-mcp@latest', '--headless', '--isolated'],
+    },
+  },
+};
+
+const yamlScalar = (s: string): string => JSON.stringify(s.replace(/\s*\n\s*/g, ' ').trim());
+
+function emitAgentFile(agent: AbstractAgent): string {
+  const frontmatter = [
+    '---',
+    `name: ${agent.name}`,
+    `description: ${yamlScalar(agent.description)}`,
+  ];
+  if (agent.deny?.length) frontmatter.push(`disallowedTools: ${agent.deny.join(', ')}`);
+  frontmatter.push('---', '');
+  return `${frontmatter.join('\n')}\n${substitute(agent.instructions)}`;
+}
+
+export function emitClaude({ agents = [] }: { agents?: AbstractAgent[] } = {}): Emitted {
+  const files: Record<string, unknown> = {};
+
+
+  for (const agent of agents) files[`agents/${agent.name}.md`] = emitAgentFile(agent);
+
+  files['.mcp.json'] = MCP_SERVERS;
+
+  files['.claude-plugin/plugin.json'] = {
+    name: 'oh-my-design',
+    description: 'Design cognition loop — frame, diverge, see, reframe',
+    skills: './skills/',
+    agents: './agents/',
+    mcpServers: './.mcp.json',
+  };
+
+  return { files };
+}
+
+// ── Plugin flavor (repo root, marketplace-installed as `oh-my-design`) ──
+//
+// A marketplace plugin loads skills/agents under its own namespace: an agent installed
+// from plugin "oh-my-design" is addressed as `oh-my-design:eye`, not `omd-eye`. The dist/
+// emission above stays bare-name for direct/manual installs and must not change. This
+// flavor is a second, parallel emission: same agents, same MCP server, but names stripped
+// of their "omd-" prefix and cross-references rewritten to the "oh-my-design:" plugin form.
+
+// "omd-scout" is both an agent and a skill name; either pattern maps it to
+// "oh-my-design:scout" — harmless overlap, the contexts (subagent spawn vs. skill mention)
+// differ. Agent pattern runs first only to keep the read order obvious; running skill
+// pattern first would be equally correct since neither pattern's output can match the
+// other's input. "omd-figma" is skill-only — it has no agent counterpart.
+const AGENT_REF = /\bomd-(composer|framer|eye|glance|hand|scout|sketch|typesetter|writer)\b/g;
+const SKILL_REF = /\bomd-(ultradesign|humanize|critique|coach|figma|scout)\b/g;
+
+const pluginizeRefs = (text: string): string => text.replace(AGENT_REF, 'oh-my-design:$1').replace(SKILL_REF, 'oh-my-design:$1');
+
+const stripOmdPrefix = (name: string): string => (name.startsWith('omd-') ? name.slice(4) : name);
+
+function emitAgentFilePlugin(agent: AbstractAgent): string {
+  const frontmatter = [
+    '---',
+    `name: ${stripOmdPrefix(agent.name)}`,
+    `description: ${yamlScalar(pluginizeRefs(agent.description))}`,
+  ];
+  if (agent.deny?.length) frontmatter.push(`disallowedTools: ${agent.deny.join(', ')}`);
+  frontmatter.push('---', '');
+  return `${frontmatter.join('\n')}\n${pluginizeRefs(substitute(agent.instructions))}`;
+}
+
+export function emitClaudePlugin({ agents = [] }: { agents?: AbstractAgent[] } = {}): Emitted {
+  const files: Record<string, unknown> = {};
+
+  for (const agent of agents) files[`agents/${stripOmdPrefix(agent.name)}.md`] = emitAgentFilePlugin(agent);
+
+  files['.mcp.json'] = MCP_SERVERS;
+
+  return { files };
+}
+
+/**
+ * Rewrites one SKILL.md source for the plugin flavor: strips "omd-" from the skill's own
+ * `name:` frontmatter (its own identity, stripped bare — same treatment as an agent's own
+ * filename/frontmatter), then rewrites every cross-reference to another skill or agent to
+ * the "oh-my-design:" plugin form. Both steps run on the whole source, so a skill's
+ * description or body mentioning another skill or agent gets the plugin-resolvable form.
+ */
+export function pluginizeSkill(source: string): { name: string; source: string } {
+  const nameLine = /^name:\s*(.+)$/m.exec(source);
+  const rawName = (nameLine?.[1] ?? '').trim().replace(/^["']|["']$/g, '');
+  const bareName = stripOmdPrefix(rawName);
+
+  let rewritten = source;
+  if (nameLine) {
+    rewritten = rewritten.slice(0, nameLine.index)
+      + `name: ${bareName}`
+      + rewritten.slice(nameLine.index + nameLine[0].length);
+  }
+  rewritten = pluginizeRefs(rewritten);
+
+  return { name: bareName, source: rewritten };
+}

package/adapters/codex.ts

@@ -0,0 +1,68 @@
+import { substituter } from './tokens.ts';
+import type { AbstractAgent, Emitted } from '../core/types.ts';
+
+const substitute = substituter('codex');
+
+// Published server, not one we run: gives the model eyes (navigate/screenshot) without
+// us hosting anything. Our own deterministic measurement stays in the `omd` CLI.
+const MCP_SERVERS = {
+  mcpServers: {
+    'chrome-devtools': {
+      command: 'npx',
+      args: ['-y', 'chrome-devtools-mcp@latest', '--headless', '--isolated'],
+    },
+  },
+};
+
+const tomlBasic = (s: string): string =>
+  `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+
+function tomlMultiline(s: string): string {
+  const body = s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+  return `"""\n${body.endsWith('\n') ? body : `${body}\n`}"""`;
+}
+
+
+/**
+ * Codex agent TOML has no tool-restriction key — only name, description, model,
+ * model_reasoning_effort, developer_instructions, nickname_candidates, service_tier.
+ * Denial is therefore prose here, not policy, exactly as Codex's own read-only agents do
+ * it. Claude Code enforces the same list declaratively via disallowedTools.
+ */
+function denialProse(deny: string[] | undefined): string {
+  if (!deny?.length) return '';
+  return `\n\nHARD CONSTRAINT: you have no write access. You must never call ${deny.join(', ')}, `
+    + 'and you must never ask another agent to write on your behalf. If a change is needed, '
+    + 'describe it and stop.\n';
+}
+
+const emitAgentFile = (agent: AbstractAgent): string => [
+  `name = ${tomlBasic(agent.name)}`,
+  `description = ${tomlBasic(agent.description)}`,
+  `model_reasoning_effort = ${tomlBasic(agent.reasoning)}`,
+  `developer_instructions = ${tomlMultiline(`${substitute(agent.instructions)}${denialProse(agent.deny)}`)}`,
+  '',
+].join('\n');
+
+export function emitCodex({ agents = [], version = '0.0.0' }: { agents?: AbstractAgent[]; version?: string } = {}): Emitted {
+  const files: Record<string, unknown> = {};
+
+  for (const agent of agents) files[`agents/${agent.name}.toml`] = emitAgentFile(agent);
+
+  files['.mcp.json'] = MCP_SERVERS;
+
+  files['.codex-plugin/plugin.json'] = {
+    name: 'oh-my-design',
+    version,
+    description: 'Design cognition loop — frame, diverge, see, reframe',
+    skills: './skills/',
+    mcpServers: './.mcp.json',
+    interface: {
+      displayName: 'Oh My Design',
+      shortDescription: 'Design cognition loop — frame, diverge, see, reframe',
+      capabilities: ['Hooks', 'Skills', 'Subagents', 'Design Lint'],
+    },
+  };
+
+  return { files };
+}

package/adapters/tokens.ts

@@ -0,0 +1,21 @@
+import toolMap from './tool-map.json' with { type: 'json' };
+import type { Host } from '../core/types.ts';
+
+interface ToolMap {
+  fileWrite: Record<Host, string>;
+  pluginRoot: Record<Host, string>;
+}
+
+const map = toolMap as unknown as ToolMap;
+
+export function substituter(host: Host): (value: string) => string {
+  const tokens: Record<string, string> = {
+    '@fileWrite': map.fileWrite[host],
+    '@pluginRoot': map.pluginRoot[host],
+  };
+  return (value: string): string => {
+    let out = value;
+    for (const [token, replacement] of Object.entries(tokens)) out = out.split(token).join(replacement);
+    return out;
+  };
+}

package/adapters/tool-map.json

@@ -0,0 +1,7 @@
+{
+  "fileWrite": { "codex": "apply_patch", "claude": "Write|Edit" },
+  "shell": { "codex": "Bash", "claude": "Bash" },
+  "pluginRoot": { "codex": "${PLUGIN_ROOT}", "claude": "$CLAUDE_PLUGIN_ROOT" },
+  "agentFormat": { "codex": "toml", "claude": "md" },
+  "hookLayout": { "codex": "file-per-hook", "claude": "single-file" }
+}

package/bin/omd-install.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectHosts } from '../core/install/detect.ts';
+import { install, uninstall, doctor } from '../core/install/install.ts';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function usage(): never {
+  console.error(
+    'usage: oh-my-design <command>\n\n'
+    + '  install     copy the plugin into every detected host and patch its config\n'
+    + '  uninstall   reverse exactly what install did (never touches .omd/)\n'
+    + '  doctor      verify the install is healthy; exits 1 if anything is broken\n'
+    + '  --version   print the oh-my-design package version',
+  );
+  process.exit(1);
+}
+
+async function main(): Promise<void> {
+  const [cmd] = process.argv.slice(2);
+
+  if (cmd === '--version') {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version: string };
+    console.log(pkg.version);
+    return;
+  }
+
+  if (cmd !== 'install' && cmd !== 'uninstall' && cmd !== 'doctor') usage();
+
+  const args = process.argv.slice(3);
+  const hostArg = args.find((a) => a.startsWith('--host'))?.split('=')[1] ?? args[args.indexOf('--host') + 1];
+
+  let hosts = detectHosts();
+  if (hostArg) {
+    hosts = hosts.filter((h) => h.host === hostArg);
+    if (hosts.length === 0) {
+      console.error(`No such host detected: ${hostArg}`);
+      process.exit(1);
+    }
+  }
+  if (hosts.length === 0) {
+    console.error('No supported host found: neither ~/.claude nor ~/.codex exists.');
+    process.exit(1);
+  }
+
+  if (cmd === 'install') {
+    for (const line of install(hosts)) console.log(line);
+    console.log(`\nInstalled for: ${hosts.map((h) => h.host).join(', ')}.`);
+    console.log('Open a session there and type /ultradesign.');
+    return;
+  }
+
+  if (cmd === 'uninstall') {
+    for (const line of uninstall(hosts)) console.log(line);
+    return;
+  }
+
+  // doctor
+  const results = doctor(hosts);
+  let failed = false;
+  for (const r of results) {
+    console.log(`${r.host}:`);
+    for (const c of r.checks) {
+      console.log(`  [${c.ok ? 'ok' : 'FAIL'}] ${c.name}${c.detail ? ` — ${c.detail}` : ''}`);
+      if (!c.ok) failed = true;
+    }
+  }
+  process.exit(failed ? 1 : 0);
+}
+
+main().catch((err: unknown) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});