@ai-outfitter/outfitter 0.9.0 → 0.10.0

package/dist/schemas/profile.schema.json

@@ -42,7 +42,7 @@
         },
         "skills": {
           "type": "array",
-          "items": { "type": "string" }
+          "items": { "$ref": "#/$defs/skillEntry" }
         },
         "prompt_template": { "type": "string" },
         "system_prompt": { "type": "string" },
@@ -81,7 +81,7 @@
             },
             "skills": {
               "type": "array",
-              "items": { "type": "string" }
+              "items": { "$ref": "#/$defs/skillEntry" }
             },
             "prompt_template": { "type": "string" },
             "system_prompt": { "type": "string" },
@@ -111,7 +111,7 @@
             },
             "skills": {
               "type": "array",
-              "items": { "type": "string" }
+              "items": { "$ref": "#/$defs/skillEntry" }
             },
             "prompt_template": { "type": "string" },
             "system_prompt": { "type": "string" },
@@ -129,6 +129,43 @@
   },
   "additionalProperties": true,
   "$defs": {
+    "skillReference": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["file"],
+          "properties": {
+            "file": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["repo_file"],
+          "properties": {
+            "repo_file": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "skillEntry": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["id"],
+          "properties": {
+            "id": { "type": "string" },
+            "references": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/skillReference" }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "appendSystemPromptEntry": {
       "oneOf": [
         { "type": "string" },

package/dist/skills/ProfileSkillResolution.d.ts

@@ -0,0 +1,21 @@
+import type { LoadedProfile } from '../profiles/ProfileLoader.js';
+import type { Profile } from '../profiles/Profile.js';
+import { type SkillResolutionDiagnostic } from './SkillResolution.js';
+export interface ProfileSkillResolutionInput {
+    readonly profile: Profile;
+    readonly profileLayers: readonly LoadedProfile[];
+    /** Materialized configured profile-source paths, in configured order. */
+    readonly sourcePaths: readonly string[];
+    readonly projectDirectory: string;
+    /** Composite profile root; generated skills are written beneath `outfitter/skills/`. */
+    readonly outputDirectory?: string;
+}
+export interface ProfileSkillResolutionResult {
+    readonly profile: Profile;
+    readonly diagnostics: readonly SkillResolutionDiagnostic[];
+}
+/**
+ * Resolves catalog skill IDs in `controls.skills` (generic and adapter-scoped) to
+ * generated skill directories, so adapters keep receiving plain path sources.
+ */
+export declare const resolveProfileSkillControls: (input: ProfileSkillResolutionInput) => ProfileSkillResolutionResult;

package/dist/skills/ProfileSkillResolution.js

@@ -0,0 +1,88 @@
+// Resolves a profile's selected skill IDs into generated skill sources before adapter launch.
+import { join } from 'node:path';
+import { inferProfileIncludeSourceRoot } from '../profiles/PromptIncludes.js';
+import { skillControlEntryIdentity } from '../agents/LaunchResources.js';
+import { discoverSkillCatalog } from './SkillCatalog.js';
+import { resolveSkillEntries, } from './SkillResolution.js';
+/**
+ * Resolves catalog skill IDs in `controls.skills` (generic and adapter-scoped) to
+ * generated skill directories, so adapters keep receiving plain path sources.
+ */
+export const resolveProfileSkillControls = (input) => {
+    const catalog = discoverSkillCatalog({
+        projectDirectory: input.projectDirectory,
+        profileLayers: input.profileLayers,
+        sourcePaths: input.sourcePaths,
+    });
+    const diagnostics = [];
+    const outputDirectory = input.outputDirectory === undefined ? undefined : join(input.outputDirectory, 'outfitter', 'skills');
+    // One skill ID materializes once; selecting it from several control scopes reuses
+    // the same generated directory, and conflicting reference sets are an error.
+    const materializationCache = new Map();
+    const resolveEntries = (entries, scope) => {
+        const resolution = resolveSkillEntries({
+            entries: entries.map((entry) => toSkillEntryInput(entry, scope, input.profileLayers)),
+            catalog,
+            projectDirectory: input.projectDirectory,
+            outputDirectory,
+            materializationCache,
+        });
+        diagnostics.push(...resolution.diagnostics);
+        return resolution.sources;
+    };
+    const controls = resolveSkillControls(input.profile.controls, resolveEntries);
+    diagnostics.push(...createShadowedSkillDiagnostics(catalog, input.profile.controls));
+    return { profile: { ...input.profile, controls }, diagnostics };
+};
+const resolveSkillControls = (controls, resolveEntries) => ({
+    ...controls,
+    ...(controls.skills === undefined ? {} : { skills: resolveEntries(controls.skills, 'skills') }),
+    ...(controls.pi?.skills === undefined
+        ? {}
+        : { pi: { ...controls.pi, skills: resolveEntries(controls.pi.skills, 'pi') } }),
+    ...(controls.claude?.skills === undefined
+        ? {}
+        : { claude: { ...controls.claude, skills: resolveEntries(controls.claude.skills, 'claude') } }),
+});
+/**
+ * Profile-added `file` references resolve from the repository containing the
+ * declaring profile. The lookup stays within the entry's own control scope so an
+ * object selection in another scope cannot supply the wrong repository root.
+ */
+const toSkillEntryInput = (entry, scope, profileLayers) => {
+    if (typeof entry === 'string') {
+        return { entry };
+    }
+    const identity = skillControlEntryIdentity(entry);
+    const declaringLayer = [...profileLayers]
+        .reverse()
+        .find((layer) => readScopedSkillEntries(layer.profile.controls, scope).some((layerEntry) => typeof layerEntry !== 'string' && skillControlEntryIdentity(layerEntry) === identity));
+    return {
+        entry,
+        profileReferenceRoot: declaringLayer === undefined
+            ? undefined
+            : inferProfileIncludeSourceRoot({
+                sourceRootPath: declaringLayer.sourceRootPath,
+                profilePath: declaringLayer.profilePath,
+            }),
+    };
+};
+const readScopedSkillEntries = (controls, scope) => (scope === 'skills' ? controls.skills : controls[scope]?.skills) ?? [];
+const readLayerSkillEntries = (controls) => [
+    ...(controls.skills ?? []),
+    ...(controls.pi?.skills ?? []),
+    ...(controls.claude?.skills ?? []),
+];
+/** Reports shadowing only for IDs the profile actually selects. */
+const createShadowedSkillDiagnostics = (catalog, controls) => {
+    const selectedIds = new Set(readLayerSkillEntries(controls).map((entry) => (typeof entry === 'string' ? entry : entry.id)));
+    return catalog.shadowed
+        .filter((shadow) => selectedIds.has(shadow.selected.id))
+        .map((shadow) => ({
+        severity: 'warning',
+        path: shadow.shadowedDirectory,
+        message: `Skill ID '${shadow.selected.id}' is supplied by ${shadow.selected.origin} ('${shadow.selected.directory}') ` +
+            `and shadows '${shadow.shadowedDirectory}'.`,
+    }));
+};
+//# sourceMappingURL=ProfileSkillResolution.js.map

package/dist/skills/ProfileSkillResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProfileSkillResolution.js","sourceRoot":"","sources":["../../src/skills/ProfileSkillResolution.ts"],"names":[],"mappings":"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"}

package/dist/skills/SkillCatalog.d.ts

@@ -0,0 +1,41 @@
+export interface SkillCatalogRoot {
+    /** Directory scanned for `<skill-id>/SKILL.md` entries. */
+    readonly skillsDirectory: string;
+    /** Root that skill `file` references resolve from (the repository containing the skill). */
+    readonly referenceRoot: string;
+    /** Human-readable origin for shadowing diagnostics. */
+    readonly origin: string;
+}
+export interface SkillCatalogEntry {
+    readonly id: string;
+    readonly directory: string;
+    readonly skillPath: string;
+    readonly referenceRoot: string;
+    readonly origin: string;
+}
+export interface SkillCatalog {
+    readonly entries: ReadonlyMap<string, SkillCatalogEntry>;
+    readonly shadowed: readonly {
+        readonly selected: SkillCatalogEntry;
+        readonly shadowedDirectory: string;
+    }[];
+}
+export interface SkillCatalogInput {
+    readonly projectDirectory?: string;
+    /** Directory-profile resource roots contributing bundled `skills/` folders. */
+    readonly profileLayers?: readonly {
+        readonly sourceRootPath?: string;
+        readonly resourceRootPath?: string;
+    }[];
+    /** Materialized configured profile-source paths, in configured (precedence) order. */
+    readonly sourcePaths?: readonly string[];
+}
+/**
+ * Builds the skill ID catalog following layer precedence: project-local, project,
+ * bundled directory-profile skills (highest-precedence layer first), then
+ * configured sources (later entries outrank earlier ones, matching profile
+ * precedence). The first root supplying an ID wins; later roots are reported as
+ * shadowed.
+ */
+export declare const discoverSkillCatalog: (input: SkillCatalogInput) => SkillCatalog;
+export declare const createSkillCatalogRoots: (input: SkillCatalogInput) => readonly SkillCatalogRoot[];

package/dist/skills/SkillCatalog.js

@@ -0,0 +1,119 @@
+// Discovers catalog skills across project, directory-profile, and configured-source roots.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { inferProfileIncludeSourceRoot } from '../profiles/PromptIncludes.js';
+import { isValidSkillId } from './SkillDocument.js';
+/**
+ * Builds the skill ID catalog following layer precedence: project-local, project,
+ * bundled directory-profile skills (highest-precedence layer first), then
+ * configured sources (later entries outrank earlier ones, matching profile
+ * precedence). The first root supplying an ID wins; later roots are reported as
+ * shadowed.
+ */
+export const discoverSkillCatalog = (input) => {
+    const entries = new Map();
+    const shadowed = [];
+    for (const root of createSkillCatalogRoots(input)) {
+        for (const entry of readSkillCatalogRootEntries(root)) {
+            const selected = entries.get(entry.id);
+            if (selected === undefined) {
+                entries.set(entry.id, entry);
+            }
+            else if (selected.directory !== entry.directory) {
+                shadowed.push({ selected, shadowedDirectory: entry.directory });
+            }
+        }
+    }
+    return { entries, shadowed };
+};
+export const createSkillCatalogRoots = (input) => {
+    const roots = [];
+    if (input.projectDirectory !== undefined) {
+        roots.push({
+            skillsDirectory: join(input.projectDirectory, '.outfitter', 'local', 'skills'),
+            referenceRoot: input.projectDirectory,
+            origin: 'project-local skills',
+        }, {
+            skillsDirectory: join(input.projectDirectory, '.outfitter', 'skills'),
+            referenceRoot: input.projectDirectory,
+            origin: 'project skills',
+        });
+    }
+    // Profile layers arrive lowest-precedence first (see ProfileMerger); reverse so
+    // the selected profile's bundled skill outranks an inherited base profile's.
+    for (const layer of [...(input.profileLayers ?? [])].reverse()) {
+        if (layer.resourceRootPath === undefined) {
+            continue;
+        }
+        roots.push({
+            skillsDirectory: join(layer.resourceRootPath, 'skills'),
+            referenceRoot: inferProfileIncludeSourceRoot({
+                sourceRootPath: layer.sourceRootPath,
+                profilePath: join(layer.resourceRootPath, 'profile.yml'),
+                /* v8 ignore next -- directory profiles always sit under a source root. */
+            }) ?? layer.resourceRootPath,
+            origin: `profile '${basename(layer.resourceRootPath)}' skills`,
+        });
+    }
+    // Later configured sources outrank earlier ones for profiles; mirror that here.
+    for (const sourcePath of [...(input.sourcePaths ?? [])].reverse()) {
+        const catalogRoot = resolveCatalogRoot(sourcePath);
+        roots.push({
+            skillsDirectory: join(catalogRoot, 'skills'),
+            referenceRoot: basename(catalogRoot) === '.outfitter' ? dirname(catalogRoot) : catalogRoot,
+            origin: `source '${sourcePath}'`,
+        });
+    }
+    return dedupeSkillCatalogRoots(roots);
+};
+/**
+ * The catalog root is the directory containing `profiles/`. A source path that
+ * points directly at the profiles directory resolves to its parent.
+ */
+const resolveCatalogRoot = (sourcePath) => basename(sourcePath) === 'profiles' ? dirname(sourcePath) : sourcePath;
+const dedupeSkillCatalogRoots = (roots) => {
+    const seen = new Set();
+    return roots.filter((root) => {
+        if (seen.has(root.skillsDirectory)) {
+            return false;
+        }
+        seen.add(root.skillsDirectory);
+        return true;
+    });
+};
+const readSkillCatalogRootEntries = (root) => readOptionalDirectoryNames(root.skillsDirectory)
+    .filter((name) => isValidSkillId(name) && existsSync(join(root.skillsDirectory, name, 'SKILL.md')))
+    .sort()
+    .map((name) => ({
+    id: name,
+    directory: join(root.skillsDirectory, name),
+    skillPath: join(root.skillsDirectory, name, 'SKILL.md'),
+    referenceRoot: root.referenceRoot,
+    origin: root.origin,
+}));
+const readOptionalDirectoryNames = (directory) => {
+    try {
+        return readdirSync(directory, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() || isSymlinkedDirectory(join(directory, entry.name), entry.isSymbolicLink()))
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return [];
+        }
+        throw new Error(`Could not read skills directory '${directory}': ${String(error)}`, { cause: error });
+    }
+};
+const isSymlinkedDirectory = (path, isSymbolicLink) => {
+    if (!isSymbolicLink) {
+        return false;
+    }
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const isMissingPathError = (error) => error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+//# sourceMappingURL=SkillCatalog.js.map

package/dist/skills/SkillCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillCatalog.js","sourceRoot":"","sources":["../../src/skills/SkillCatalog.ts"],"names":[],"mappings":"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"}

package/dist/skills/SkillDocument.d.ts

@@ -0,0 +1,21 @@
+import type { SkillReference } from '../profiles/Profile.js';
+export declare const isSkillReference: (value: unknown) => value is SkillReference;
+/** Frontmatter keys that materialize external files into a generated skill directory. */
+export declare const skillMaterializationSections: readonly ["references", "scripts", "assets"];
+export type SkillMaterializationSection = (typeof skillMaterializationSections)[number];
+export interface SkillDocument {
+    readonly name: string;
+    readonly description?: string;
+    readonly references: readonly SkillReference[];
+    readonly scripts: readonly SkillReference[];
+    readonly assets: readonly SkillReference[];
+}
+export interface SkillDocumentIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/** Skill IDs and directory names: lowercase alphanumerics and single hyphens, at most 64 characters. */
+export declare const isValidSkillId: (value: string) => boolean;
+export declare const parseSkillDocument: (content: string, skillPath: string) => SkillDocument | SkillDocumentIssue;
+export declare const readSkillDocument: (skillPath: string) => SkillDocument | SkillDocumentIssue;
+export declare const isSkillDocumentIssue: (value: SkillDocument | SkillDocumentIssue) => value is SkillDocumentIssue;

package/dist/skills/SkillDocument.js

@@ -0,0 +1,85 @@
+// Parses and validates SKILL.md frontmatter for catalog skill resolution.
+import { readFileSync } from 'node:fs';
+import { parseYamlDocument } from '../validation/YamlDocument.js';
+export const isSkillReference = (value) => value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 1 &&
+    (typeof value.file === 'string' ||
+        typeof value.repo_file === 'string');
+const skillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const skillNameMaxLength = 64;
+/** Frontmatter keys that materialize external files into a generated skill directory. */
+export const skillMaterializationSections = ['references', 'scripts', 'assets'];
+/** Skill IDs and directory names: lowercase alphanumerics and single hyphens, at most 64 characters. */
+export const isValidSkillId = (value) => value.length <= skillNameMaxLength && skillNamePattern.test(value);
+export const parseSkillDocument = (content, skillPath) => {
+    const frontmatter = parseSkillFrontmatter(content, skillPath);
+    if ('message' in frontmatter) {
+        return frontmatter;
+    }
+    const { name, description } = frontmatter.record;
+    if (typeof name !== 'string' || !isValidSkillId(name)) {
+        return {
+            path: skillPath,
+            message: `SKILL.md 'name' must use lowercase letters, numbers, and single hyphens ` +
+                `(max ${skillNameMaxLength} characters).`,
+        };
+    }
+    const sections = {};
+    for (const section of skillMaterializationSections) {
+        const entries = frontmatter.record[section];
+        if (entries !== undefined && (!Array.isArray(entries) || !entries.every(isSkillReference))) {
+            return {
+                path: skillPath,
+                message: `SKILL.md '${section}' entries must each contain exactly one 'file' or 'repo_file' source.`,
+            };
+        }
+        sections[section] = entries ?? [];
+    }
+    return {
+        name,
+        description: typeof description === 'string' ? description : undefined,
+        references: sections.references,
+        scripts: sections.scripts,
+        assets: sections.assets,
+    };
+};
+const parseSkillFrontmatter = (content, skillPath) => {
+    const frontmatter = extractFrontmatter(content);
+    if (frontmatter === undefined) {
+        return { path: skillPath, message: 'SKILL.md must start with a `---` YAML frontmatter block.' };
+    }
+    const parsed = parseYamlDocument(frontmatter, skillPath);
+    if (!parsed.ok) {
+        return { path: skillPath, message: `SKILL.md frontmatter is not valid YAML: ${parsed.issue.message}` };
+    }
+    const record = parsed.document;
+    if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+        return { path: skillPath, message: 'SKILL.md frontmatter must be a YAML mapping.' };
+    }
+    return { record: record };
+};
+export const readSkillDocument = (skillPath) => {
+    let content;
+    try {
+        content = readFileSync(skillPath, 'utf8');
+    }
+    catch (error) {
+        return { path: skillPath, message: `Could not read SKILL.md: ${String(error)}` };
+    }
+    return parseSkillDocument(content, skillPath);
+};
+export const isSkillDocumentIssue = (value) => 'message' in value;
+const extractFrontmatter = (content) => {
+    const lines = content.split('\n');
+    if (lines[0]?.trimEnd() !== '---') {
+        return undefined;
+    }
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trimEnd() === '---');
+    if (closingIndex === -1) {
+        return undefined;
+    }
+    return lines.slice(1, closingIndex).join('\n');
+};
+//# sourceMappingURL=SkillDocument.js.map

package/dist/skills/SkillDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillDocument.js","sourceRoot":"","sources":["../../src/skills/SkillDocument.ts"],"names":[],"mappings":"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"}

package/dist/skills/SkillResolution.d.ts

@@ -0,0 +1,34 @@
+import type { SkillControlEntry } from '../profiles/Profile.js';
+import type { SkillCatalog } from './SkillCatalog.js';
+export interface SkillResolutionDiagnostic {
+    readonly severity: 'error' | 'warning';
+    readonly path: string;
+    readonly message: string;
+}
+export interface SkillEntryInput {
+    readonly entry: SkillControlEntry;
+    /** Root for `file` references appended by the declaring profile. */
+    readonly profileReferenceRoot?: string;
+}
+/**
+ * Shared across control scopes so one skill ID materializes once; a second
+ * selection reuses the generated directory, and differing reference sets error.
+ */
+export type SkillMaterializationCache = Map<string, {
+    readonly referencesKey: string;
+    readonly generatedDirectory?: string;
+}>;
+export interface SkillResolutionInput {
+    readonly entries: readonly SkillEntryInput[];
+    readonly catalog: SkillCatalog;
+    readonly projectDirectory?: string;
+    /** When set, resolved skills are copied here as `<id>/` with materialized references. */
+    readonly outputDirectory?: string;
+    readonly materializationCache?: SkillMaterializationCache;
+}
+export interface SkillResolutionResult {
+    /** Skill sources in entry order: generated directories for resolved IDs, original strings otherwise. */
+    readonly sources: readonly string[];
+    readonly diagnostics: readonly SkillResolutionDiagnostic[];
+}
+export declare const resolveSkillEntries: (input: SkillResolutionInput) => SkillResolutionResult;