@epicparty/skills 0.1.0 → 0.1.1

package/README.md

@@ -65,7 +65,7 @@ The skills in this repository are written with the prefix `ep`, and the router's
 - links into a sibling skill's folder, `../<skill>/`, to `../<prefix>-<skill>/`, and `../router/` to `../<prefix>/`;
 - each `SKILL.md`'s `name` to its installed name: `router` becomes `<prefix>`.
 
-Then it checks the result: every name matches its folder, every link and heading anchor resolves, and every skill named in the text is installed. Each skill also carries `pack: epicparty/skills` under `metadata`, which is how `/<prefix>-setup` finds the pack's skills whatever the prefix.
+Then it checks the result: every name matches its folder, every link and heading anchor resolves, and every skill named in the text is installed. Only a pack skill's name counts as a skill reference, so any prefix works, including one that starts English words: with `up`, "an up-to-date base" stays text. Each skill also carries `pack: epicparty/skills` under `metadata`, which is how `/<prefix>-setup` finds the pack's skills whatever the prefix.
 
 `npx @epicparty/skills check` runs the same check on an installed project.
 
@@ -99,9 +99,10 @@ Releases run on [Changesets](https://github.com/changesets/changesets), the way
 
 1. **Every pull request that changes the pack adds a changeset** — `npx changeset` — whose entry starts with the skills it changes. [`.changeset/README.md`](./.changeset/README.md) has the format and the bump levels. CI fails a pull request that changes a skill and names it in no changeset.
 2. **On each push to `main`**, the Release workflow opens or updates a `chore: release` pull request. It bumps the pack's version and each named skill's, and writes `CHANGELOG.md`.
-3. **Merging that pull request is the release.** The workflow tags `v<version>` and publishes a GitHub release from the changelog.
+3. **Merging that pull request stages the release.** The workflow stages the new version on npm through [trusted publishing](https://docs.npmjs.com/trusted-publishers) — no npm token is stored anywhere — tags `v<version>`, and publishes a GitHub release from the changelog.
+4. **A maintainer approves it with 2FA**, and only then can anyone install it: on npmjs.com under the package's staged versions, or `npm stage list @epicparty/skills`, then `npm stage approve <stage-id>`. The run's summary says so. If staging failed, run the Release workflow by hand once the cause is fixed.
 
-Until npm publishing is on, a project installs a release from GitHub: `npx github:epicparty/skills#v<version> add --prefix acme`. To turn npm on, set up [trusted publishing](https://docs.npmjs.com/trusted-publishers) for `@epicparty/skills`, add `id-token: write` to the workflow's permissions, and change its `publish-script` to `npx changeset publish`.
+npm must trust the workflow to stage, and only to stage: on npmjs.com, `@epicparty/skills` → **Settings** → **Trusted publishing** names GitHub Actions, `epicparty/skills`, `release.yml`, no environment, with **Allow npm publish** unticked. A run that could publish directly would skip the 2FA approval.
 
 The GitHub repository must allow it: **Settings → Actions → General → Allow GitHub Actions to create and approve pull requests**.
 

package/bin/cli.mjs

@@ -7,7 +7,7 @@ import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { build, check, packSkills, skillVersion, validatePrefix } from '../lib/transform.mjs';
+import { build, check, checkSource, packSkills, skillVersion, validatePrefix } from '../lib/transform.mjs';
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
@@ -100,6 +100,8 @@ function sourceDir(from) {
 }
 
 function buildChecked(source, prefix, out) {
+  const sourceProblems = checkSource(source);
+  if (sourceProblems.length) fail(`the skills in ${source} are inconsistent:\n  ${sourceProblems.join('\n  ')}`);
   const names = build(source, prefix, out);
   const problems = check(out, prefix, { canonicalSkills: packSkills(source) });
   if (problems.length) fail(`the built skills are inconsistent:\n  ${problems.join('\n  ')}`);
@@ -167,7 +169,7 @@ else if (command === 'update') {
   const names = buildChecked(sourceDir(opts.from), validatePrefix(opts.prefix), resolve(opts.out));
   console.log(`Built ${names.length} skills in ${resolve(opts.out)}`);
 } else if (command === 'check') {
-  const prefix = validatePrefix(opts.prefix ?? readLock(cwd)?.prefix ?? fail('check needs --prefix'));
+  const prefix = validatePrefix(opts.prefix ?? readLock(cwd)?.prefix ?? fail(`no ${LOCK} here to read the prefix from: pass --prefix <p>`));
   const dir = resolve(rest[0] ?? '.agents/skills');
   const problems = check(dir, prefix, { canonicalSkills: packSkills(sourceDir(opts.from)) });
   if (problems.length) fail(`${problems.length} problem(s):\n  ${problems.join('\n  ')}`);

package/lib/transform.mjs

@@ -130,12 +130,42 @@ function anchors(text) {
   return out;
 }
 
+/** Matches a skill reference written with `prefix`: `<prefix>-<name>` or `/<prefix>-<name>`, or `<prefix>-*`. */
+function referenceRe(prefix, names) {
+  return new RegExp(`(?<![\\w-])/?${escape(prefix)}-(${names}|\\*)(?![\\w-])`, 'g');
+}
+
 /**
- * Checks installed pack skills in dir (folders named <prefix>-<skill> and <prefix>).
+ * Checks the pack's own source: every `ep-<name>` it writes names a skill of the pack. The
+ * canonical prefix is the pack's to choose, so in the source any `ep-<name>` is a reference, and
+ * one the rewrite does not know (a typo, a removed skill) is reported here.
  * Returns a list of problems; empty means consistent.
  */
+export function checkSource(sourceDir) {
+  const skills = new Set(packSkills(sourceDir));
+  const problems = [];
+  for (const file of walk(sourceDir).filter((f) => f.endsWith('.md'))) {
+    for (const m of readFileSync(file, 'utf8').matchAll(referenceRe(CANONICAL, '[a-z0-9]+(?:-[a-z0-9]+)*'))) {
+      if (m[1] !== '*' && (m[1] === ROUTER || !skills.has(m[1]))) {
+        problems.push(`${relative(sourceDir, file)}: names ${m[0]}, which is not a skill in the pack`);
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Checks installed pack skills in dir (folders named <prefix>-<skill> and <prefix>), given the
+ * pack's skill folders. Returns a list of problems; empty means consistent.
+ *
+ * A `<prefix>-<name>` counts as a skill reference only when <name> is one of the pack's skills,
+ * because only those are what the rewrite produces. Any other `<prefix>-<word>` is the text's own:
+ * with the prefix `up`, "an up-to-date base" is English, not a skill named `to-date`.
+ * `checkSource` catches a source reference to a skill the pack does not have.
+ */
 export function check(dir, prefix, { canonicalSkills } = {}) {
   validatePrefix(prefix);
+  if (!canonicalSkills?.length) throw new TypeError('check needs canonicalSkills: the skill folders of the pack');
   const problems = [];
   const installed = readdirSync(dir).filter((name) => {
     const file = join(dir, name, 'SKILL.md');
@@ -143,10 +173,14 @@ export function check(dir, prefix, { canonicalSkills } = {}) {
   });
   const set = new Set(installed);
   if (!set.has(prefix)) problems.push(`router "${prefix}" is not installed`);
-  const nameRe = new RegExp(`(?<![\\w-])/?${escape(prefix)}-([a-z0-9]+(?:-[a-z0-9]+)*|\\*)(?![\\w-])`, 'g');
-  const canonical = canonicalSkills?.filter((s) => s !== ROUTER).map(escape).join('|');
+  const canonical = canonicalSkills
+    .filter((s) => s !== ROUTER)
+    .sort((a, b) => b.length - a.length)
+    .map(escape)
+    .join('|');
+  const nameRe = referenceRe(prefix, canonical);
   const leftovers = [];
-  if (prefix !== CANONICAL && canonical) leftovers.push(`(?<![\\w-])${CANONICAL}-(?:${canonical})(?![\\w-])`, `(?<![\\w/.-])/${CANONICAL}(?![\\w-])`);
+  if (prefix !== CANONICAL) leftovers.push(`(?<![\\w-])${CANONICAL}-(?:${canonical})(?![\\w-])`, `(?<![\\w/.-])/${CANONICAL}(?![\\w-])`);
   if (prefix !== ROUTER) leftovers.push(`\\.\\./${ROUTER}/`);
   const leftover = leftovers.length ? new RegExp(leftovers.join('|'), 'g') : null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epicparty/skills",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A delivery workflow for coding agents — explore, story, implement, PR, ship — installed under your project's own prefix.",
   "license": "MIT",
   "type": "module",