From 5ee1183d226f3f364d3ab4cf36566ec27389ddc5 Mon Sep 17 00:00:00 2001 From: Kirby <996@itdog.icu> Date: Wed, 4 Nov 2026 10:27:39 +0800 Subject: [PATCH] fix: make public overview catalog-driven without a fixed plugin count Generate the README plugin index alongside the native marketplace and derive validation inventory from catalog declarations. Keep About positioning independent of the current catalog size. Co-Authored-By: Claude Opus 5 --- CONTRIBUTING.md | 4 ++-- README.md | 18 ++++++++++-------- scripts/catalog.mjs | 22 +++++++++++++++++++--- 3 files changed, 31 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8566cc1..9b73182 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,12 @@ This repository publishes plugin instructions and pinned native CLI supply metad ## Update the catalog -The root `marketplace.json` is the authority for plugin IDs, plugin versions, component inventory, CLI supply versions, archive URLs and digests. `.claude-plugin/marketplace.json` is its generated native Claude Code projection. Do not maintain the same catalog twice. +The root `marketplace.json` is the authority for plugin IDs, plugin versions, component inventory, CLI supply versions, archive URLs and digests. `.claude-plugin/marketplace.json` and the marked plugin table in `README.md` are generated projections. Do not hand-edit the table or freeze a plugin count in the repository's title, About or positioning. Adding a plugin requires its catalog entry and own guide, not a rewrite of the repository overview. 1. Edit the relevant plugin, manifest and root catalog together. Distinguish plugin version, archive wrapper version and actual executable version; expert previews must not be relabeled as stable. 2. Check that every declared skill/agent exists and relative references work. Native plugin installations need a useful guide even when a compatible Cortex Host would replace it with a release-owned skill. Native plugin installation does not provision a CLI. 3. Update user documentation when behavior, prerequisites, platforms, permissions or download availability change. Link the official spreadsheet skill and its license rather than copying it. -4. Regenerate the native marketplace: +4. Regenerate the native marketplace and README plugin index: ```bash npm run generate diff --git a/README.md b/README.md index 5bd761c..40272ea 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,16 @@ Find background datasets, prepare an openLCA study, work with product carbon-foo ## Choose a plugin -| Plugin | What you can do | Plugin version | Native CLI / status | -| --- | --- | --- | --- | -| [Nora organization Wiki](plugins/cortex-org-wiki/README.md) | Find published organization knowledge, read exact page versions and cite sources | 0.1.6 | `cortex-org-wiki` 0.1.5 | -| [HiQ Editor](plugins/hiq-editor/README.md) | Prepare UPR workbooks, inspect preflight results, import and trial-calculate with authorization | 0.12.0 | `hiq-editor` 0.12.0 | -| [LCA dataset lookup & matching](plugins/querying-lca-datasets-expert/README.md) | Find background process datasets and match inventory items with provenance and unit evidence | 0.5.1 | `querying-lca-datasets` 0.5.1 | -| [JiMULCA](plugins/jimu-lca/README.md) | Inspect or revise product carbon-footprint cases, bind backgrounds and calculate when authorized | 0.2.2 | `jimu-lca` 0.2.1; macOS Apple Silicon only | -| [openLCA modeling — prerelease](plugins/cortex-lca-expert/README.md) | Turn process records or an existing model into an openLCA study, calculation and evidence-backed interpretation | 0.1.1 | `cortex-lca-expert` **0.1.0-dev.14** | -| [EPD review — demo prerelease](plugins/cortex-epd/README.md) | Prepare an EPD review engagement and explain CLI-produced findings and evidence | 0.1.1 | `cortex-epd` **0.1.0-dev.14.candidate.39933331655.1.2**; demo-only, not approved for formal promotion | + +| Plugin | Description | +| --- | --- | +| [cortex-org-wiki](plugins/cortex-org-wiki/README.md) | Search Nora's published organization Wiki and read versioned pages with source citations. Use the CLI's own Cortex login and the intended organization. | +| [hiq-editor](plugins/hiq-editor/README.md) | HiQ Editor toolkit: the native CLI release, its canonical UPR workflow skill and evidence-based authoring/review agents. | +| [querying-lca-datasets-expert](plugins/querying-lca-datasets-expert/README.md) | Query LCA process datasets and match inventory requirements using the self-contained querying-lca-datasets CLI, with provenance and representativeness review. | +| [jimu-lca](plugins/jimu-lca/README.md) | Inspect JiMULCA product carbon-footprint cases and run authorized inventory, binding and calculation operations with the user's own member credential. | +| [cortex-lca-expert](plugins/cortex-lca-expert/README.md) | Preview wrapper for cortex-lca-expert 0.1.0-dev.14: build, inspect and calculate openLCA models using the user's installed application and Cortex expert authorization. Wrapper version 0.1.0 is not a stable CLI release. | +| [cortex-epd](plugins/cortex-epd/README.md) | Demo-only prerelease wrapper for cortex-epd 0.1.0-dev.14.candidate.39933331655.1.2. EPD pre-audit instructions come from that complete candidate. HOLD remains in effect; this is not promotion, product acceptance or certification. | + For both expert plugins, `0.1.0` in the download path and Cortex supply metadata is the **archive wrapper version**, not a stable CLI version. The executable versions are shown above. EPD's newer development source does not make a newer downloadable release available. This catalog does not supply EPD dev.21. diff --git a/scripts/catalog.mjs b/scripts/catalog.mjs index 1334388..7b94722 100644 --- a/scripts/catalog.mjs +++ b/scripts/catalog.mjs @@ -15,15 +15,17 @@ const checkComponent = (plugin, relative) => { } }; const catalog = JSON.parse(read('marketplace.json')); -const expected = ['cortex-epd', 'cortex-lca-expert', 'cortex-org-wiki', 'hiq-editor', 'jimu-lca', 'querying-lca-datasets-expert']; -assert.deepEqual(catalog.plugins.map(p => p.id).sort(), expected); -assert.deepEqual(readdirSync(path.join(root, 'plugins')).sort(), expected); +const ids = catalog.plugins.map(plugin => plugin.id); +assert.ok(ids.length, 'The catalog must contain plugins'); +assert.equal(new Set(ids).size, ids.length, 'Plugin IDs must be unique'); +assert.deepEqual(readdirSync(path.join(root, 'plugins')).sort(), [...ids].sort()); const native = { name: 'hiq-plugins', owner: { name: 'HiQ' }, metadata: { description: 'HiQ service plugins with native CLI operating guides.' }, plugins: catalog.plugins.map(plugin => { assert.equal(plugin.type, 'plugin'); + assert.match(plugin.id, /^[a-z0-9]+(?:-[a-z0-9]+)*$/); assert.equal(plugin.path, `plugins/${plugin.id}`); const manifest = JSON.parse(read(`${plugin.path}/.claude-plugin/plugin.json`)); assert.equal(manifest.name, plugin.id); @@ -52,10 +54,24 @@ const native = { }), }; const generated = `${JSON.stringify(native, null, 2)}\n`; +const marker = /[\s\S]*?/; +const readme = read('README.md'); +assert.match(readme, marker, 'README catalog markers are required'); +const escapeCell = value => value.replaceAll('|', '\\|').replaceAll('\n', ' '); +const overview = [ + '', + '| Plugin | Description |', + '| --- | --- |', + ...native.plugins.map(plugin => `| [${plugin.name}](plugins/${plugin.name}/README.md) | ${escapeCell(plugin.description)} |`), + '', +].join('\n'); +const generatedReadme = readme.replace(marker, () => overview); if (process.argv.includes('--write')) { mkdirSync(path.join(root, '.claude-plugin'), { recursive: true }); writeFileSync(path.join(root, '.claude-plugin/marketplace.json'), generated); + writeFileSync(path.join(root, 'README.md'), generatedReadme); } else { assert.equal(read('.claude-plugin/marketplace.json'), generated, 'Run npm run generate'); + assert.equal(readme, generatedReadme, 'Run npm run generate to update the README catalog'); } console.log(`Validated ${native.plugins.length} plugins, component paths, CLI pins and native index.`);