pattyeng 1.0.4 → 1.0.7

package/skills/.system/openai-docs/scripts/resolve-latest-model-info.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const DEFAULT_URL =
+  "https://developers.openai.com/api/docs/guides/latest-model.md";
+const DEFAULT_BASE_URL = "https://developers.openai.com";
+
+function parseArgs(argv) {
+  const args = {
+    source: process.env.LATEST_MODEL_URL || DEFAULT_URL,
+    baseUrl: process.env.LATEST_MODEL_BASE_URL || DEFAULT_BASE_URL,
+  };
+
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--source" || arg === "--url") {
+      args.source = argv[i + 1];
+      i += 1;
+    } else if (arg === "--base-url") {
+      args.baseUrl = argv[i + 1];
+      i += 1;
+    }
+  }
+
+  return args;
+}
+
+async function readSource(source) {
+  if (source.startsWith("file://")) {
+    return fs.readFile(new URL(source), "utf8");
+  }
+
+  if (!/^https?:\/\//.test(source)) {
+    return fs.readFile(path.resolve(source), "utf8");
+  }
+
+  const response = await fetch(source, {
+    headers: { accept: "text/markdown,text/plain,*/*" },
+  });
+
+  if (!response.ok) {
+    throw new Error(`failed to fetch ${source}: ${response.status}`);
+  }
+
+  return response.text();
+}
+
+function parseIndentedInfo(lines, startIndex) {
+  const info = {};
+
+  for (let i = startIndex + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      continue;
+    }
+
+    const match = line.match(/^ {2}([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (!match) {
+      break;
+    }
+
+    info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+  }
+
+  return info;
+}
+
+function parseFlatInfo(block) {
+  const info = {};
+
+  for (const line of block.split(/\r?\n/)) {
+    const match = line.match(/^\s*([A-Za-z][A-Za-z0-9_-]*):\s*(.+?)\s*$/);
+    if (match) {
+      info[match[1]] = match[2].replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return info;
+}
+
+function extractLatestModelInfo(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const latestModelInfoIndex = lines.findIndex((line) =>
+    /^latestModelInfo:\s*$/.test(line)
+  );
+
+  if (latestModelInfoIndex >= 0) {
+    return parseIndentedInfo(lines, latestModelInfoIndex);
+  }
+
+  const commentMatch = markdown.match(
+    /<!--\s*latestModelInfo\s*\n([\s\S]*?)\n\s*-->/m
+  );
+  if (commentMatch) {
+    return parseFlatInfo(commentMatch[1]);
+  }
+
+  return undefined;
+}
+
+function modelToSkillSlug(model) {
+  return model.trim().replace(/\./g, "p");
+}
+
+function absoluteUrl(baseUrl, value) {
+  return new URL(value, baseUrl).toString();
+}
+
+function normalizeInfo(info, baseUrl) {
+  const model = info?.model?.trim();
+  const migrationGuide = info?.migrationGuide?.trim();
+  const promptingGuide = info?.promptingGuide?.trim();
+
+  if (!model || !migrationGuide || !promptingGuide) {
+    throw new Error(
+      "latestModelInfo must include model, migrationGuide, and promptingGuide"
+    );
+  }
+
+  return {
+    model,
+    modelSlug: modelToSkillSlug(model),
+    migrationGuideUrl: absoluteUrl(baseUrl, migrationGuide),
+    promptingGuideUrl: absoluteUrl(baseUrl, promptingGuide),
+  };
+}
+
+async function main() {
+  const { source, baseUrl } = parseArgs(process.argv);
+  const markdown = await readSource(source);
+  const info = extractLatestModelInfo(markdown);
+
+  if (!info) {
+    throw new Error(`latestModelInfo block not found in ${source}`);
+  }
+
+  process.stdout.write(
+    `${JSON.stringify(normalizeInfo(info, baseUrl), null, 2)}\n`
+  );
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/skills/.system/plugin-creator/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: plugin-creator
+description: Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
+---
+
+# Plugin Creator
+
+## Quick Start
+
+1. Run the scaffold script:
+
+```bash
+# Plugin names are normalized to lower-case hyphen-case and must be <= 64 chars.
+# The generated folder and plugin.json name are always the same.
+# Run from the skill root (the directory containing this `SKILL.md`).
+# By default creates in `~/plugins/<plugin-name>`.
+python3 scripts/create_basic_plugin.py <plugin-name>
+```
+
+2. Edit `<plugin-path>/.codex-plugin/plugin.json` when the request gives specific metadata.
+   The scaffold starts with valid defaults and must not contain `[TODO: ...]` placeholders.
+
+3. Generate or update the personal marketplace entry when the plugin should appear in Codex UI ordering:
+
+```bash
+# Personal marketplace entries default to `~/.agents/plugins/marketplace.json`.
+python3 scripts/create_basic_plugin.py my-plugin --with-marketplace
+```
+
+Only specify `--marketplace-name <name>` when the default `personal` marketplace name is already
+taken or installed and you need to seed a different new marketplace file:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --with-marketplace \
+  --marketplace-name team-local
+```
+
+Only use a repo/team marketplace when the user specifically asks for that destination:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <repo-root>/plugins \
+  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
+  --with-marketplace
+```
+
+When the user specifies a marketplace path, make sure that marketplace is actually installed before
+telling the user to reinstall from it. The default personal marketplace file at
+`~/.agents/plugins/marketplace.json` is discovered implicitly, but other marketplace paths are not.
+On Windows, use the equivalent path under the user profile.
+
+4. Generate/adjust optional companion folders as needed:
+
+```bash
+python3 scripts/create_basic_plugin.py my-plugin \
+  --path <parent-plugin-directory> \
+  --marketplace-path <marketplace-json-path> \
+  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace
+```
+
+`<parent-plugin-directory>` is the directory where the plugin folder `<plugin-name>` will be
+created (for example `~/plugins`).
+
+5. Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```
+
+For updates to an existing local plugin during development, keep the scaffold flow as-is and use the
+reference instead of hand-editing marketplace files:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py <plugin-path>
+```
+
+Prefer the helper default cachebuster unless the user explicitly asks for a specific override.
+See `references/installing-and-updating.md` for the expected cachebuster and reinstall flow while iterating on an existing local plugin.
+
+## What this skill creates
+
+- Default marketplace-backed scaffolds use the personal marketplace file at
+  `~/.agents/plugins/marketplace.json`, with plugins generally being stored in
+  `~/plugins/<plugin-name>/`.
+- Creates plugin root at `/<parent-plugin-directory>/<plugin-name>/`.
+- Always creates `/<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json`.
+- Fills the manifest with the validated schema shape that the ingestion path accepts.
+- Creates or updates `~/.agents/plugins/marketplace.json` when `--with-marketplace` is set.
+  - If the marketplace file does not exist yet, seed a personal marketplace root before adding the first plugin entry.
+- `<plugin-name>` is normalized using skill-creator naming rules:
+  - `My Plugin` → `my-plugin`
+  - `My--Plugin` → `my-plugin`
+  - underscores, spaces, and punctuation are converted to `-`
+  - result is lower-case hyphen-delimited with consecutive hyphens collapsed
+- Supports optional creation of:
+  - `skills/`
+  - `hooks/`
+  - `scripts/`
+  - `assets/`
+  - `.mcp.json`
+  - `.app.json`
+
+## Marketplace workflow
+
+- Personal-marketplace creation defaults to `~/.agents/plugins/marketplace.json`. Here,
+  "personal marketplace" means the marketplace whose file is at that path.
+- Repo/team marketplace creation is opt-in through both `--path` and `--marketplace-path`, only
+  when the user specifically requests it.
+- `--marketplace-name` is an exception path. Use it only when the default `personal` marketplace
+  name is already taken and you need to seed a different new marketplace file.
+- Do not use `--marketplace-name` to rename an existing marketplace file in place. If the file
+  already exists, its top-level `name` must already match.
+- If the user specifies a different marketplace path, treat that marketplace as needing explicit installation via `codex plugin marketplace add`.
+- Prefer `scripts/read_marketplace_name.py` when you need the marketplace name from any
+  `marketplace.json` file. With no argument it reads the default personal marketplace; with an
+  explicit path it works for repo/team marketplaces too.
+- In either location, the generated source path remains `./plugins/<plugin-name>`.
+- Marketplace root metadata supports top-level `name` plus optional `interface.displayName`.
+- Treat plugin order in `plugins[]` as render order in Codex. Append new entries unless a user explicitly asks to reorder the list.
+- `displayName` belongs inside the marketplace `interface` object, not individual `plugins[]` entries.
+- Each generated marketplace entry must include all of:
+  - `policy.installation`
+  - `policy.authentication`
+  - `category`
+- Default new entries to:
+  - `policy.installation: "AVAILABLE"`
+  - `policy.authentication: "ON_INSTALL"`
+- Override defaults only when the user explicitly specifies another allowed value.
+- Allowed `policy.installation` values:
+  - `NOT_AVAILABLE`
+  - `AVAILABLE`
+  - `INSTALLED_BY_DEFAULT`
+- Allowed `policy.authentication` values:
+  - `ON_INSTALL`
+  - `ON_USE`
+- Treat `policy.products` as an override. Omit it unless the user explicitly requests product gating.
+- The generated plugin entry shape is:
+
+```json
+{
+  "name": "plugin-name",
+  "source": {
+    "source": "local",
+    "path": "./plugins/plugin-name"
+  },
+  "policy": {
+    "installation": "AVAILABLE",
+    "authentication": "ON_INSTALL"
+  },
+  "category": "Productivity"
+}
+```
+
+- Use `--force` only when intentionally replacing an existing marketplace entry for the same plugin name.
+- If the target marketplace file does not exist yet, create it with top-level `"name"`, an `"interface"` object containing `"displayName"`, and a `plugins` array, then add the new entry.
+
+- For a brand-new marketplace file, the root object should look like:
+
+```json
+{
+  "name": "personal",
+  "interface": {
+    "displayName": "Personal"
+  },
+  "plugins": [
+    {
+      "name": "plugin-name",
+      "source": {
+        "source": "local",
+        "path": "./plugins/plugin-name"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}
+```
+
+## Required behavior
+
+- Outer folder name and `plugin.json` `"name"` are always the same normalized plugin name.
+- Do not remove required structure; keep `.codex-plugin/plugin.json` present.
+- Do not leave `[TODO: ...]` placeholders in plugin manifests.
+- Keep `apps` and `mcpServers` out of `plugin.json` unless their companion files are actually created.
+- Omit unsupported plugin manifest fields that validation rejects, including `hooks`.
+- If creating files inside an existing plugin path, use `--force` only when overwrite is intentional.
+- Preserve any existing marketplace `interface.displayName`.
+- When generating marketplace entries, always write `policy.installation`, `policy.authentication`, and `category` even if their values are defaults.
+- Add `policy.products` only when the user explicitly asks for that override.
+- Keep marketplace `source.path` relative to the selected marketplace root as `./plugins/<plugin-name>`.
+- Only use `--marketplace-name` when creating a new marketplace file whose name should not be
+  `personal` because that name is already taken or installed elsewhere.
+- If Codex would need approval to write the marketplace file, ask for that approval before
+  proceeding. If the user prefers to run the write themselves, provide the exact scaffold command
+  and then continue from validation or subsequent plugin edits instead of leaving the workflow
+  vague.
+- For updates to an existing local plugin during development, do not hand-edit marketplace config
+  or `marketplace.json`. Use the update flow documented in
+  `references/installing-and-updating.md` and `scripts/update_plugin_cachebuster.py`.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That command is for explicit non-default marketplace configuration, not for the standard
+  `~/.agents/plugins/marketplace.json` path.
+- If the user provided a non-default `--marketplace-path`, make sure that marketplace is installed
+  before giving reinstall instructions. Use `codex plugin marketplace add <path-to-marketplace-root>`
+  when that explicit marketplace has not been configured yet.
+- When the workflow created or updated a marketplace-backed plugin, end the final user-facing
+  response with a short Codex app handoff. Say `To view this in the Codex app:` and write
+  `View <normalized plugin name>` and `Share <normalized plugin name>` as Markdown links, not raw
+  URLs or code spans.
+- The View deeplink uses `codex://plugins/<normalized plugin name>?marketplacePath=<absolute marketplace.json path>`.
+  The Share deeplink uses the same URL with `&mode=share`.
+- Replace the placeholders with the real normalized plugin name and absolute `marketplace.json`
+  path from the scaffolded plugin. URL-encode the path segment and query value when needed.
+- Do not add `pluginName` or `hostId` query parameters to these deeplinks. Codex derives both after
+  the user clicks the link.
+- Do not emit the `View <normalized plugin name>` or `Share <normalized plugin name>` links when no marketplace entry was
+  created or updated.
+
+## Reference to exact spec sample
+
+For the exact canonical sample JSON for both plugin manifests and marketplace entries, use:
+
+- `references/plugin-json-spec.md`
+- `references/installing-and-updating.md` for update/reinstall guidance while
+  iterating on an existing local plugin, plus the new-thread pickup behavior after reinstall
+
+## Validation
+
+After editing `SKILL.md`, run:
+
+```bash
+python3 ../skill-creator/scripts/quick_validate.py .
+```
+
+Before handing back a generated plugin, run:
+
+```bash
+python3 scripts/validate_plugin.py <plugin-path>
+```

package/skills/.system/plugin-creator/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plugin Creator"
+  short_description: "Scaffold plugins and marketplace entries"
+  default_prompt: "Use $plugin-creator to scaffold a valid plugin in the personal marketplace, then validate it before handing it back."
+  icon_small: "./assets/plugin-creator-small.svg"
+  icon_large: "./assets/plugin-creator.png"

package/skills/.system/plugin-creator/assets/plugin-creator-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 20 20">
+  <path fill="#0D0D0D" d="M12.03 4.113a3.612 3.612 0 0 1 5.108 5.108l-6.292 6.29c-.324.324-.56.561-.791.752l-.235.176c-.205.14-.422.261-.65.36l-.229.093a4.136 4.136 0 0 1-.586.16l-.764.134-2.394.4c-.142.024-.294.05-.423.06-.098.007-.232.01-.378-.026l-.149-.05a1.081 1.081 0 0 1-.521-.474l-.046-.093a1.104 1.104 0 0 1-.075-.527c.01-.129.035-.28.06-.422l.398-2.394c.1-.602.162-.987.295-1.35l.093-.23c.1-.228.22-.445.36-.65l.176-.235c.19-.232.428-.467.751-.79l6.292-6.292Zm-5.35 7.232c-.35.35-.534.535-.66.688l-.11.147a2.67 2.67 0 0 0-.24.433l-.062.154c-.08.22-.124.462-.232 1.112l-.398 2.394-.001.001h.003l2.393-.399.717-.126a2.63 2.63 0 0 0 .394-.105l.154-.063a2.65 2.65 0 0 0 .433-.24l.147-.11c.153-.126.339-.31.688-.66l4.988-4.988-3.227-3.226-4.987 4.988Zm9.517-6.291a2.281 2.281 0 0 0-3.225 0l-.364.362 3.226 3.227.363-.364c.89-.89.89-2.334 0-3.225ZM4.583 1.783a.3.3 0 0 1 .294.241c.117.585.347 1.092.707 1.48.357.385.859.668 1.549.783a.3.3 0 0 1 0 .592c-.69.115-1.192.398-1.549.783-.315.34-.53.77-.657 1.265l-.05.215a.3.3 0 0 1-.588 0c-.117-.585-.347-1.092-.707-1.48-.357-.384-.859-.668-1.549-.783a.3.3 0 0 1 0-.592c.69-.115 1.192-.398 1.549-.783.36-.388.59-.895.707-1.48l.015-.05a.3.3 0 0 1 .279-.19Z"/>
+</svg>

package/skills/.system/plugin-creator/references/installing-and-updating.md

@@ -0,0 +1,143 @@
+# Updating Existing Local Plugins
+
+Use this reference when a plugin already exists and the request is about updating the plugin during 
+local development.
+
+All scripts here are specified relative to the skill root. Update the path for running the scripts
+depending on your current working directory.
+
+## When To Use This Flow
+
+Use this flow when all of the following are true:
+
+- the plugin already exists locally
+- the marketplace entry already points at the plugin source you are editing
+- the user wants Codex to see the updated plugin without manually editing marketplace files
+
+If the user still needs the initial plugin entry or marketplace structure created, use the scaffold
+flow first and only then switch to this reinstall flow.
+
+## Update Loop
+
+1. Update the plugin manifest to a single Codex cachebuster suffix:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path>
+```
+
+Prefer the default helper behavior here. If you omit `--cachebuster`, the helper uses a UTC
+timestamp down to seconds, which is the recommended path for routine local iteration.
+
+Only use a manual cachebuster override when the user explicitly asks for one or when a workflow
+outside Codex depends on a specific token:
+
+```bash
+python3 scripts/update_plugin_cachebuster.py \
+  <plugin-path> \
+  --cachebuster local-20260519-184516
+```
+
+2. For the default scaffolded flow, read the marketplace name from the personal marketplace file:
+
+```bash
+python3 scripts/read_marketplace_name.py
+```
+
+Here, "personal marketplace" means the marketplace whose file is at
+`~/.agents/plugins/marketplace.json`. On Windows, use the equivalent path under the user profile.
+The helper uses Python's home-directory resolution and prints the marketplace name to use when
+constructing the install command.
+
+To read the name from a different marketplace file, pass the path directly:
+
+```bash
+python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>
+```
+
+3. Reinstall from that marketplace name:
+
+```bash
+codex plugin add <plugin-name>@<marketplace-name-from-marketplace-json>
+```
+
+The default personal marketplace is discovered implicitly from
+`~/.agents/plugins/marketplace.json`. You do not need `codex plugin marketplace add` for that
+path, and `codex plugin marketplace list` is not the right check for whether that default
+marketplace exists.
+
+4. If the plugin is not using the personal marketplace file, check which configured local
+   marketplace is actually surfacing that plugin:
+
+```bash
+codex plugin list
+```
+
+If the plugin is not in the personal marketplace file, confirm which marketplace entry points at
+the plugin source you are editing and make sure that marketplace is still local. If it is a
+different local marketplace, reinstall from that marketplace name instead of forcing the personal
+marketplace flow. If it is not local, stop and help the user resolve the mismatch before
+continuing.
+
+5. If the plugin lives in a different confirmed local marketplace, substitute that marketplace
+   name:
+
+```bash
+codex plugin add <plugin-name>@<local-marketplace>
+```
+
+6. Prompt the user to use a new thread to try the updated plugin, so that Codex picks up new skills
+   and tools.
+
+## Cachebuster Policy
+
+- Preserve the existing version prefix and replace only the suffix.
+- Treat the preserved prefix as everything before `+`.
+- Use the format:
+
+```text
+<base-version>+codex.<cachebuster>
+```
+
+Examples:
+
+- `0.1.0` → `0.1.0+codex.local-20260519-184516`
+- `0.1.0+codex.old-token` → `0.1.0+codex.local-20260519-184516`
+- `1.2.3-beta.1+codex.prev` → `1.2.3-beta.1+codex.local-20260519-184516`
+- `dev-build+other-tag` → `dev-build+codex.local-20260519-184516`
+
+Replace the existing Codex cachebuster instead of appending another one. Do not keep incrementing
+numeric version components just to trigger reinstall behavior.
+
+## Marketplace Rules
+
+- Marketplace manipulation should happen through commands, not by hand-editing `marketplace.json`
+  or `config.toml` during this update/reinstall flow.
+- Prefer the personal marketplace file for the default scaffolded flow.
+- Read the personal marketplace name with
+  `python3 scripts/read_marketplace_name.py` and use the printed value when constructing
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- For non-default marketplace files, use
+  `python3 scripts/read_marketplace_name.py --marketplace-path <path-to-marketplace.json>` to read
+  the name before constructing reinstall commands.
+- Do not tell the user to run `codex plugin marketplace add` for the default personal-marketplace
+  flow. That marketplace is discovered implicitly by Codex.
+- If the user specified a different marketplace path, make sure that marketplace is installed
+  before giving install or reinstall instructions. Non-default marketplace paths are not
+  discovered implicitly.
+- Use `codex plugin list` when the plugin lives in a different configured marketplace and you need
+  to confirm which marketplace is surfacing that plugin.
+- If a non-default local marketplace has not been configured yet, install it with
+  `codex plugin marketplace add <path-to-marketplace-root>` before telling the user to run
+  `codex plugin add <plugin-name>@<marketplace-name>`.
+- If the plugin is not in the personal marketplace file, confirm that the selected marketplace is
+  local before telling the user to reinstall from it.
+- If the selected marketplace is not local, stop and help the user resolve that mismatch rather
+  than pretending the normal local reinstall flow applies.
+- If the plugin source is not already the source referenced by the chosen marketplace entry, stop
+  and fix that first. This update flow does not rewrite marketplace entries.
+
+## After Reinstall
+
+After reinstalling, prompt the user to start a new thread for testing. That is the safe boundary for
+picking up the updated plugin and its MCP tools.