@csark0812/skeleton 1.1.0 → 1.1.2

package/README.md

@@ -1,5 +1,9 @@
 # Skeleton
 
+**Source of truth for** Package overview.
+
+<!-- doc-meta: owner=eng | last-reviewed=2026-07-13 -->
+
 Single source of truth (SSOT) linter for agent-enabled repos.
 
 Agent repos accumulate skills, rules, registries, and cross-linked docs faster than anyone can keep them straight by hand. Code repos solved this decades ago with ESLint — deterministic checks, CI gates, fix what you can before merge. Skeleton does the same job for documentation architecture: what's canonical, what links where, what must not exist, and whether your skill overrides are wired correctly.
@@ -83,12 +87,12 @@ skeleton customize resolve <slug>
 
 **Validate changed** routes git diffs to the right audit:
 
-| Path                                         | Action                      |
-| -------------------------------------------- | --------------------------- |
-| Docs/skills in scan perimeter                | path-scoped audit           |
-| `.sh`, `.bash`, `.zsh`                       | shellcheck or `bash -n`     |
-| Other `.json`                                | JSONC-tolerant syntax check |
-| `.ts`, `.py`, `package.json`, `project.json` | skip                        |
+| Path                                                              | Action                      |
+| ----------------------------------------------------------------- | --------------------------- |
+| Docs/skills in scan perimeter                                     | path-scoped audit           |
+| `.sh`, `.bash`, `.zsh`                                            | shellcheck or `bash -n`     |
+| Other `.json`                                                     | JSONC-tolerant syntax check |
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `package.json`, `project.json` | skip (exits 1 if all skip) |
 
 Pre-commit: `skeleton validate changed --staged` (path-scoped, fast).
 CI: `skeleton validate changed --base origin/main` (global rules first, then changed files).
@@ -128,11 +132,18 @@ One command for humans: `npx skeleton init --skills`.
 
 ## Development
 
-Requires Node ≥ 22. Uses Bun for dev and tests.
+Requires Node ≥ 22. Uses Bun for dev and tests. Agent cold-start: [AGENTS.md](AGENTS.md).
 
 ```bash
 bun install
 bun test
+bun run typecheck
 bun run build
 bun run audit:self
 ```
+
+`validate:changed` is docs/skills only — it skips code/config extensions (see table). All-skip inputs exit non-zero. Use `bun test` and `bun run typecheck` for code.
+
+### Publishing 1.1.2 (human)
+
+Keep version `1.1.2` until `npm publish`. Preflight: `bun test && bun run typecheck && bun run build && bun run audit:self`. Then publish and tag when ready (npm is still on `1.1.1` until then).

package/dist/cli.js

@@ -16536,7 +16536,8 @@ var $visitAsync = visit.visitAsync;
 // src/audit/config/load.ts
 var SCHEMA_CANDIDATES = [
   join(dirname2(fileURLToPath2(import.meta.url)), "../../../schemas/config.schema.json"),
-  join(dirname2(fileURLToPath2(import.meta.url)), "../schemas/config.schema.json")
+  join(dirname2(fileURLToPath2(import.meta.url)), "../schemas/config.schema.json"),
+  join(dirname2(fileURLToPath2(import.meta.url)), "../../schemas/config.schema.json")
 ];
 function resolveSchemaPath() {
   for (const candidate of SCHEMA_CANDIDATES) {
@@ -16594,6 +16595,9 @@ function mergedExcludes(config) {
 function retiredSkills(config) {
   return config.scan.retiredSkills ?? [];
 }
+function nonPublicSkills(config) {
+  return config.scan.nonPublicSkills ?? [];
+}
 
 // src/audit/core/skill-roots.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readlinkSync, realpathSync as realpathSync2 } from "node:fs";
@@ -28604,7 +28608,6 @@ function isGeneratedReference(content3) {
 }
 
 // src/audit/rules/skill-index.ts
-var NON_PUBLIC_SLUGS = new Set(["align-commands"]);
 function walkSkillMarkdown(dir) {
   const files = [];
   if (!existsSync8(dir))
@@ -28658,6 +28661,7 @@ function scanFileForSkillLinks(ctx, filePath, index2) {
 }
 function validateReadmeTaxonomy(ctx, index2, diskSlugs) {
   const issues = [];
+  const nonPublic = new Set(nonPublicSkills(ctx.config));
   for (const skillRoot of index2.roots) {
     if (skillRoot.kind !== "nested")
       continue;
@@ -28669,7 +28673,7 @@ function validateReadmeTaxonomy(ctx, index2, diskSlugs) {
       continue;
     const taxonomySlugs = parseReadmeTaxonomySlugs(readme);
     const nestedSlugs = diskSlugs.filter((slug2) => existsSync8(join8(ctx.root, skillRoot.relPath, slug2, "SKILL.md")));
-    const publicSlugs = nestedSlugs.filter((slug2) => !NON_PUBLIC_SLUGS.has(slug2));
+    const publicSlugs = nestedSlugs.filter((slug2) => !nonPublic.has(slug2));
     const relReadme = `${skillRoot.relPath}/README.md`;
     for (const slug2 of publicSlugs) {
       if (!taxonomySlugs.includes(slug2)) {
@@ -28763,10 +28767,16 @@ function findLocalCanonicalLinks(root2, content3, sourceFile) {
   }
   const inReferencesDir = /\/references\//.test(sourceFile);
   if (inReferencesDir) {
+    const refsIdx = sourceFile.lastIndexOf("/references/");
+    const withinRefs = sourceFile.slice(refsIdx + "/references/".length);
+    const withinDir = withinRefs.includes("/") ? withinRefs.slice(0, withinRefs.lastIndexOf("/")) : "";
     const siblingRe = /\((?!https?:|#|\.\.\/)([a-z0-9./_-]+\.md)\)/gi;
     for (const match of content3.matchAll(siblingRe)) {
-      const refPath = normalizeRelPath(match[1] ?? "");
-      if (!refPath || !canonicalExists(root2, refPath))
+      const raw = normalizeRelPath(match[1] ?? "");
+      if (!raw)
+        continue;
+      const refPath = withinDir ? normalizeRelPath(join9(withinDir, raw)) : raw;
+      if (!canonicalExists(root2, refPath))
         continue;
       links.push({ refPath, sourceFile });
     }
@@ -28795,6 +28805,21 @@ function discoverSkillReferencePlans(root2) {
         links.push(link2);
       }
     }
+    const queue = [...refPaths];
+    while (queue.length > 0) {
+      const refPath = queue.pop();
+      if (!refPath || !canonicalExists(root2, refPath))
+        continue;
+      const canonicalContent = readFileSync8(join9(root2, CANONICAL_REFS_DIR, refPath), "utf8");
+      const syntheticSource = generatedRefPath(slug2, refPath);
+      for (const link2 of findLocalCanonicalLinks(root2, canonicalContent, syntheticSource)) {
+        if (refPaths.has(link2.refPath))
+          continue;
+        refPaths.add(link2.refPath);
+        links.push(link2);
+        queue.push(link2.refPath);
+      }
+    }
     if (refPaths.size > 0) {
       plans.push({ skill: slug2, refPaths, links });
     }
@@ -29022,10 +29047,13 @@ function runAudit(options) {
 
 // src/customize/resolve.ts
 import { existsSync as existsSync11, readFileSync as readFileSync10 } from "node:fs";
-import { join as join11, relative as relative8 } from "node:path";
+import { basename as basename2, join as join11, relative as relative8 } from "node:path";
 var CUSTOMIZE_PREFIX = "Customize: ";
+function customizeDir(root2) {
+  return join11(root2, REGISTRY_DIR_REL, "customize");
+}
 function customizePathForSlug(root2, slug2) {
-  return join11(root2, REGISTRY_DIR_REL, "customize", `${slug2}.md`);
+  return join11(customizeDir(root2), `${slug2}.md`);
 }
 function findCustomizeViaRegistry(root2, slug2) {
   for (const rel of parseRegistryPaths(root2)) {
@@ -29036,11 +29064,10 @@ function findCustomizeViaRegistry(root2, slug2) {
   }
   return null;
 }
-function resolveCustomize(root2, slug2) {
+function resolveSlugFile(root2, slug2) {
   const direct = customizePathForSlug(root2, slug2);
   if (existsSync11(direct)) {
     return {
-      slug: slug2,
       content: readFileSync10(direct, "utf8"),
       path: normalizeRelPath(relative8(root2, direct))
     };
@@ -29049,12 +29076,64 @@ function resolveCustomize(root2, slug2) {
   if (registryPath) {
     const abs = join11(root2, registryPath);
     return {
-      slug: slug2,
       content: readFileSync10(abs, "utf8"),
       path: registryPath
     };
   }
-  return { slug: slug2, content: null, path: null };
+  return { content: null, path: null };
+}
+function alwaysIncludeBasenames(root2) {
+  try {
+    const config = loadConfig(root2);
+    return config.customize?.alwaysInclude ?? [];
+  } catch {
+    return [];
+  }
+}
+function readAlwaysInclude(root2, basenames, skipBasename) {
+  const parts = [];
+  const paths = [];
+  const dir = customizeDir(root2);
+  for (const name of basenames) {
+    const file = basename2(name);
+    if (skipBasename && file === skipBasename)
+      continue;
+    const abs = join11(dir, file);
+    if (!existsSync11(abs))
+      continue;
+    parts.push(readFileSync10(abs, "utf8").trimEnd());
+    paths.push(normalizeRelPath(relative8(root2, abs)));
+  }
+  return { parts, paths };
+}
+function resolveCustomize(root2, slug2) {
+  const slugFile = resolveSlugFile(root2, slug2);
+  const alwaysNames = alwaysIncludeBasenames(root2);
+  const skip = slugFile.path != null ? basename2(slugFile.path) : null;
+  const always = readAlwaysInclude(root2, alwaysNames, skip);
+  const parts = [];
+  const included = [];
+  if (slugFile.content != null && slugFile.content.trim().length > 0) {
+    parts.push(slugFile.content.trimEnd());
+    if (slugFile.path)
+      included.push(slugFile.path);
+  }
+  parts.push(...always.parts);
+  included.push(...always.paths);
+  if (parts.length === 0) {
+    return { slug: slug2, content: null, path: slugFile.path, included: [] };
+  }
+  return {
+    slug: slug2,
+    content: parts.join(`
+
+---
+
+`) + `
+`,
+    path: slugFile.path ?? always.paths[0] ?? null,
+    included
+  };
 }
 function resolveCustomizeFromRoot(slug2, startDir) {
   const root2 = findRepoRoot(startDir);
@@ -29610,7 +29689,7 @@ function registerPath(options) {
 
 // src/validate/changed.ts
 import { existsSync as existsSync17, readFileSync as readFileSync14 } from "node:fs";
-import { basename as basename2, extname, join as join17 } from "node:path";
+import { basename as basename3, extname, join as join17 } from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 
 // src/validate/git-diff.ts
@@ -29641,7 +29720,7 @@ var COMMAND_CONFIG_NAMES = new Set(["package.json", "project.json"]);
 function bucketFor(relPath2, root2) {
   const normalized = normalizeRelPath(relPath2);
   const ext = extname(normalized).toLowerCase();
-  const name = basename2(normalized);
+  const name = basename3(normalized);
   if (SKIP_EXTENSIONS.has(ext))
     return "skip";
   if (COMMAND_CONFIG_NAMES.has(name))
@@ -29732,6 +29811,7 @@ function runValidateChanged(options = {}) {
     }
     buckets[bucket].push(relPath2);
   }
+  const audited = buckets.docs.length + buckets.skills.length + buckets.shell.length + buckets.json.length;
   let exitCode = 0;
   if (options.base) {
     const globalExit = runAudit({
@@ -29746,6 +29826,12 @@ function runValidateChanged(options = {}) {
     if (globalExit !== 0)
       exitCode = 1;
   }
+  if (skipped > 0 && audited === 0) {
+    console.error(`validate changed: all paths were skipped (code/config). This does not verify TypeScript or app code.
+` + `  In this repo: bun test && bun run typecheck
+` + "  Consumers: run your local code validation gates.");
+    return 1;
+  }
   if (buckets.docs.length > 0) {
     const docExit = runAudit({
       suite: "docs",
@@ -30007,7 +30093,12 @@ function main() {
         console.error("register: path required");
         process.exit(1);
       }
-      registerPath(opts);
+      registerPath({
+        path: opts.path,
+        topic: opts.topic,
+        dryRun: opts.dryRun,
+        json: opts.json
+      });
       process.exit(0);
     }
     if (command === "customize" && argv[1] === "resolve") {