@baselane/packs 0.1.0

package/dist/seed-skills.js

@@ -0,0 +1,134 @@
+import { readdir, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join, relative, sep } from "node:path";
+import { validateSkill } from "./validate.js";
+/** Source tag for baselane-authored first-party skills (#19). Distinguishes them from imported
+ * (third-party) seed skills and is the basis of the catalog's first-party/third-party filter.
+ * First-party skills carry no external licence notice and no `attribution`. */
+export const FIRST_PARTY_SOURCE = "baselane";
+/** Absolute path of the committed seed-skills directory shipped inside this package. */
+export function seedSkillsDir() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+/** Every file under `dir`, recursively, as POSIX-style paths relative to `dir` (sorted). Mirrors
+ * the walk in @baselane/analyze's LocalDirFileSource. */
+async function walkFiles(dir) {
+    const out = [];
+    const visit = async (sub) => {
+        const entries = await readdir(sub, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(sub, entry.name);
+            if (entry.isDirectory())
+                await visit(full);
+            else if (entry.isFile())
+                out.push(relative(dir, full).split(sep).join("/"));
+        }
+    };
+    await visit(dir);
+    return out.sort();
+}
+/** Turns a relative file path (its markdown extension already stripped) into a valid reference-
+ * name slug. Mirrors ingest.ts's private `slugify()` — same transform, so a name derived here from
+ * a vendored skill's directory and a name recovered by ingesting an already-rendered repo agree
+ * for the same file, letting a skill round-trip render↔ingest. Extended (vs. ingest.ts's one-
+ * level-deep sibling scan) to fold a nested path's separators into the same dash-joined slug,
+ * since a vendored skill's companions (e.g. mcp-builder's `reference/*.md`) are frequently nested. */
+function slugifyRefPath(value) {
+    const s = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return s.length > 0 ? s : "x";
+}
+/** Every companion `.md` file in a seed skill's directory (recursively, SKILL.md excluded), turned
+ * into SkillReference blocks the render pipeline emits under `.claude/skills/<name>/<ref>.md`
+ * (render/claude.ts's skillMd/reference emission is flat and always appends `.md`, so only
+ * markdown companions can become a reference at all). Non-markdown companions the importer
+ * vendors alongside SKILL.md — scripts, assets, LICENSE — have no representation in that flat,
+ * markdown-only model; they stay on disk as vendored content without becoming a reference. A name
+ * collision after slugifying (two different paths reducing to the same slug) keeps the first and
+ * drops the rest — rare, and no worse than dropping the file outright, so it's silent rather than
+ * a load-time throw. */
+async function loadReferences(skillDir) {
+    const files = await walkFiles(skillDir);
+    const out = [];
+    const seen = new Set();
+    for (const relPath of files) {
+        if (relPath === "SKILL.md" || !relPath.endsWith(".md"))
+            continue;
+        const body = await readFile(join(skillDir, relPath), "utf8");
+        if (body.length === 0)
+            continue; // an empty reference would fail validateSkill's non-empty-body rule
+        const name = slugifyRefPath(relPath.slice(0, -".md".length));
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        out.push({ name, body });
+    }
+    return out;
+}
+function parseBody(md) {
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(md);
+    const fm = {};
+    if (m)
+        for (const raw of m[1].split("\n")) {
+            const kv = /^([a-zA-Z0-9_-]+):\s*(.*)$/.exec(raw.trim());
+            if (kv)
+                fm[kv[1]] = kv[2].replace(/^["']|["']$/g, "");
+        }
+    return { name: fm.name ?? "", description: (fm.description ?? "").trim(), body: (m ? m[2] : md).trimEnd() + "\n" };
+}
+/** Loads baselane-authored first-party skills from `skills/first-party/` (#19). Kept in a separate
+ * subtree the import script never wipes, so re-running the fetch can't clobber them. A first-party
+ * skill carries no external licence text and no `attribution` — its provenance is the source tag.
+ * Returns [] when the subtree is absent; a present-but-malformed manifest or an invalid skill
+ * throws (the seed must never ship an invalid skill — same contract as the fetched path). */
+async function loadFirstPartySkills(dir) {
+    const fpDir = join(dir, "first-party");
+    let raw;
+    try {
+        raw = await readFile(join(fpDir, "manifest.json"), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const manifest = JSON.parse(raw);
+    const out = [];
+    for (const entry of manifest.skills) {
+        const md = await readFile(join(fpDir, entry.name, "SKILL.md"), "utf8");
+        const parsed = parseBody(md);
+        const block = validateSkill({
+            name: parsed.name || entry.name,
+            description: parsed.description,
+            body: parsed.body,
+            category: entry.category,
+        });
+        out.push({ block, licenseText: "", source: FIRST_PARTY_SOURCE, url: "", sha: "" });
+    }
+    return out;
+}
+/** Reads and VALIDATES every committed seed skill (validateSkill is the sole authority). Throws if
+ * any seed no longer conforms — the seed must never ship an invalid skill. First-party skills are
+ * appended after the fetched (third-party) ones, so callers keying off index order are unaffected. */
+export async function loadSeedSkills() {
+    const dir = seedSkillsDir();
+    const manifest = JSON.parse(await readFile(join(dir, "seed-manifest.json"), "utf8"));
+    const shaByRepo = new Map(manifest.sources.map((s) => [s.repo, s.sha]));
+    const out = [];
+    for (const entry of manifest.skills) {
+        const skillDir = join(dir, entry.name);
+        const md = await readFile(join(skillDir, "SKILL.md"), "utf8");
+        const licenseText = await readFile(join(skillDir, "LICENSE"), "utf8");
+        const parsed = parseBody(md);
+        const references = await loadReferences(skillDir);
+        const block = validateSkill({
+            name: parsed.name || entry.name,
+            description: parsed.description,
+            body: parsed.body,
+            category: entry.category,
+            attribution: { source: entry.source, url: entry.url, license: entry.license },
+            ...(references.length > 0 ? { references } : {}),
+        });
+        out.push({ block, licenseText, source: entry.source, url: entry.url, sha: shaByRepo.get(entry.source) ?? "" });
+    }
+    return [...out, ...(await loadFirstPartySkills(dir))];
+}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+export type PackScope = "repo" | "developer" | "both";
+/** A single onboarding step a pack recommends after adoption (increment 28). `command` is a
+ * display/exec string shown to the developer — never shell-interpolated with user input. */
+export interface OnboardingStep {
+    id: string;
+    title: string;
+    description: string;
+    command?: string;
+}
+/** Link from a pack block back to the org component-library entry it was copied from
+ * (increment 26). Optional and additive: absent on every built-in pack, round-tripped by
+ * validatePack, and NEVER printed into any rendered file. */
+export interface BlockProvenance {
+    componentId: string;
+    version: number;
+}
+/** One MCP server an agent declares in its frontmatter (e.g. Playwright). Preserved from harness
+ * bundles that scope tools per-agent; renders back as nested YAML under `mcpServers:`. Optional and
+ * additive — absent on every built-in agent, so existing agent frontmatter renders unchanged. */
+export interface McpServerConfig {
+    command: string;
+    args?: string[];
+}
+/** Locked canonical pack schema — see docs/superpowers/research/2026-06-25-substrate-eval.md */
+export interface PackAgent {
+    name: string;
+    description: string;
+    tools: string[];
+    model: string;
+    prompt: string;
+    provenance?: BlockProvenance;
+    /** Per-agent MCP servers (map of server name → command/args). Absent on built-ins. */
+    mcpServers?: Record<string, McpServerConfig>;
+}
+export interface PackCommand {
+    name: string;
+    description: string;
+    argument_hint: string;
+    prompt: string;
+    provenance?: BlockProvenance;
+}
+interface PackHookBase {
+    event: string;
+    matcher: string;
+    description: string;
+    provenance?: BlockProvenance;
+}
+export type PackHook = (PackHookBase & {
+    action: "print-reminder";
+    message: string;
+}) | (PackHookBase & {
+    action: "run-command";
+    command: string;
+});
+export interface Capability {
+    type: "memory" | "tasks" | "wiki" | "graph" | "design" | "system-map";
+    store: "org" | "repo";
+    method: string;
+    config?: Record<string, string>;
+    provenance?: BlockProvenance;
+}
+/** A single progressive-disclosure reference file bundled beside a skill's SKILL.md (increment 29).
+ * `name` is a slug (one level deep — no slashes); it renders as `<name>.md` next to SKILL.md. */
+export interface SkillReference {
+    name: string;
+    body: string;
+}
+/** An agentskills.io-standard skill as a pack block (increment 29). `category` is a baselane-side
+ * taxonomy slug and is NEVER written into SKILL.md frontmatter. `attribution` retains an imported
+ * skill's licence notice; `provenance` links a copied block back to its library SkillRecord. */
+export interface SkillBlock {
+    name: string;
+    description: string;
+    body: string;
+    category: string;
+    references?: SkillReference[];
+    attribution?: {
+        source: string;
+        url: string;
+        license: string;
+    };
+    provenance?: BlockProvenance;
+    /** Governance frontmatter (2026 skills⇄commands merge). All optional and additive: absent on
+     * existing skills, so their SKILL.md renders byte-identically. Rendered as kebab-case keys
+     * (`user-invocable` / `disable-model-invocation` / `allowed-tools`) when present. */
+    userInvocable?: boolean;
+    disableModelInvocation?: boolean;
+    allowedTools?: string[];
+}
+export interface WorkflowPack {
+    id: string;
+    version: string;
+    title: string;
+    summary: string;
+    context: {
+        markdown: string;
+    };
+    attribution?: {
+        source: string;
+        url: string;
+        license: string;
+    };
+    /** Who this pack targets. Absent → treated as "repo" (see packScope()). */
+    scope?: PackScope;
+    capabilities?: Capability[];
+    /** Recommended post-adoption steps, tracked per target in the portal. */
+    onboarding?: OnboardingStep[];
+    /** Skills this pack renders (Option A). Absent → treated as []; never mutated into the object. */
+    skills?: SkillBlock[];
+    /** #23: names of packs/skills this one overlaps with — a catalog cross-link so a user doesn't
+     * double-install near-duplicates. Library/catalog metadata only; never rendered into a file. */
+    relatedTo?: string[];
+    /** #23: names of packs this one is meant to replace — a stronger "use this instead of X" signal
+     * than relatedTo. Library/catalog metadata only; never rendered. */
+    supersedes?: string[];
+    agents: PackAgent[];
+    commands: PackCommand[];
+    hooks: PackHook[];
+}
+/** Rendered output: repo-relative POSIX path → file content. */
+export type FileMap = Record<string, string>;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,30 @@
+import type { Capability, PackAgent, PackCommand, PackHook, PackScope, SkillBlock, WorkflowPack } from "./types.ts";
+export declare const KNOWN_HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", "Stop", "SubagentStop", "PreCompact", "SessionStart", "SessionEnd"];
+export declare const SKILL_NAME_MAX = 64;
+export declare const SKILL_DESC_MAX = 1024;
+export declare const SKILL_BODY_MAX_LINES = 500;
+export declare const SKILL_BODY_WARN_LINES = 400;
+export interface SkillLint {
+    field: string;
+    message: string;
+}
+/** The sole authority on a SkillBlock — mirrors validatePack for skills. Throws (like validatePack)
+ * on anything invalid; callers guard. */
+export declare function validateSkill(raw: unknown): SkillBlock;
+/** Non-throwing soft advisories surfaced when a skill is created or edited (portal's
+ * /app/skills/save, rendered as an amber notice by skillsPage — never blocks a save): warns when a
+ * body nears the 500-line ceiling, and when a name contains "anthropic"/"claude" (agentskills.io's
+ * public-upload anti-impersonation signal — worth an admin's attention here, but not a reject).
+ * Hard violations are rejected by validateSkill; this only surfaces amber. */
+export declare function skillLints(block: SkillBlock): SkillLint[];
+export declare function validatePack(raw: unknown): WorkflowPack;
+export type ComponentBlockType = "agent" | "command" | "hook" | "rules" | "capability";
+/** Validates a single reusable library-component payload by reusing the EXACT block validators
+ * validatePack uses (`agent`/`command`/`hook`/`capability` above) — so a stored component can never
+ * encode a block validatePack would later reject. Returns the canonical, extra-field-stripped block
+ * (or the markdown string for "rules"). Throws (like validatePack) on anything invalid; callers guard. */
+export declare function validateComponent(blockType: ComponentBlockType, payload: unknown): PackAgent | PackCommand | PackHook | Capability | string;
+/** The pack's target scope, defaulting an absent scope to "repo" so every pre-increment-28 pack
+ * (built-in or custom) keeps today's repo behavior. This is the ONLY place the default is applied —
+ * validatePack never injects `scope` into the object, so a pack's bytes round-trip unchanged. */
+export declare function packScope(pack: WorkflowPack): PackScope;