@cat-factory/agents 0.59.2 → 0.61.0

package/dist/skillLibrary/SkillSourceService.js

@@ -0,0 +1,237 @@
+import { NotFoundError, ValidationError, assertFound } from '@cat-factory/kernel';
+import { normalizeDirPath, probeRepoSourceStatus, syncRepoSource, } from '../repoSourceSync/repo-source-sync.js';
+import { isSkillManifest, parseSkillManifest, slugFromDirName } from './skill-source.logic.js';
+/**
+ * Repo-sourced Claude skills (docs/initiatives/repo-skills.md): link a repo
+ * directory of skill folders to an account, resync it (read each `<skill>/SKILL.md`
+ * directory, upsert changed skills, tombstone removed ones), and answer the cheap
+ * "check for changes" without writing. Reads go through the account's existing
+ * GitHub installation — no new credential store. The shared repo-source engine
+ * (repoSourceSync) owns the sync mechanics; this service supplies the skill
+ * differentiator: the sync unit is a DIRECTORY (`<skill>/SKILL.md` + its sibling
+ * resources), and a resource-only edit (which advances the dir head commit without
+ * touching `SKILL.md`'s blob sha) is caught by re-reading whenever the pinned commit
+ * moved.
+ */
+export class SkillSourceService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Linked sources for an account + their last-synced state. */
+    async list(accountId) {
+        const rows = await this.deps.skillSourceRepository.listByAccount(accountId);
+        return rows.map(toWire);
+    }
+    /** Link a repo directory as a skill source. Does not sync (call {@link sync}). */
+    async link(accountId, input) {
+        const now = this.deps.clock.now();
+        const record = {
+            id: this.deps.idGenerator.next('sklsrc'),
+            accountId,
+            repoOwner: input.repoOwner.trim(),
+            repoName: input.repoName.trim(),
+            gitRef: input.gitRef?.trim() || 'HEAD',
+            dirPath: normalizeDirPath(input.dirPath),
+            lastSyncedCommit: null,
+            lastSyncedAt: null,
+            createdAt: now,
+            deletedAt: null,
+        };
+        await this.deps.skillSourceRepository.upsert(record);
+        return toWire(record);
+    }
+    /** Unlink a source and tombstone every skill it produced. */
+    async unlink(accountId, sourceId) {
+        const source = await this.require(accountId, sourceId);
+        const now = this.deps.clock.now();
+        const skills = await this.deps.accountSkillRepository.listBySource(sourceId);
+        if (skills.length > 0) {
+            await this.deps.accountSkillRepository.softDeleteBySource(sourceId, now);
+        }
+        await this.deps.skillSourceRepository.softDelete(source.id, now);
+        if (skills.length > 0)
+            await this.deps.invalidateCatalog?.(accountId);
+    }
+    /**
+     * Resync a source: read each `<skill>/SKILL.md` directory, upsert every skill whose
+     * manifest or resource manifest changed, tombstone skills no longer produced, and
+     * stamp the source dir's head commit. Idempotent — re-running with no upstream change
+     * touches nothing.
+     */
+    async sync(accountId, sourceId) {
+        const source = await this.require(accountId, sourceId);
+        const installationId = await this.requireInstallation(source);
+        return syncRepoSource({
+            source,
+            installationId,
+            githubClient: this.deps.githubClient,
+            now: this.deps.clock.now(),
+            listExisting: () => this.deps.accountSkillRepository.listBySource(sourceId),
+            existingId: (s) => s.skillId,
+            reconcile: async ({ readRef, commitMoved, now }, existing) => {
+                const existingById = new Map(existing.map((s) => [s.skillId, s]));
+                // The head commit for the whole source dir is the exact staleness signal: if it
+                // has not advanced since the last sync, NOTHING under it changed (manifest OR
+                // resource), so every skill is unchanged and we skip all per-directory reads.
+                if (!commitMoved) {
+                    return {
+                        liveIds: new Set(existing.map((s) => s.skillId)),
+                        upserted: 0,
+                        unchanged: existing.length,
+                    };
+                }
+                // Sort dirs by name (code-unit order, locale-independent) so slug-collision
+                // resolution is deterministic — first wins — regardless of ICU collation.
+                const dirs = (await this.listDir(source, installationId, source.dirPath, readRef))
+                    .filter((e) => e.type === 'dir')
+                    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+                const liveIds = new Set();
+                const seenSlugs = new Set();
+                let upserted = 0;
+                let unchanged = 0;
+                let incomplete = false;
+                for (const dir of dirs) {
+                    const slug = slugFromDirName(dir.name);
+                    // Two sibling dirs can slug to the same id (e.g. `release_notes` + `release-notes`,
+                    // both → `release-notes`). Keep the first (sorted order) deterministically and skip
+                    // the rest rather than silently overwriting one skill's row with another's.
+                    if (seenSlugs.has(slug))
+                        continue;
+                    seenSlugs.add(slug);
+                    const skillId = `src:${source.id}:${slug}`;
+                    const synced = await this.syncSkillDir(source, dir.name, dir.path, skillId, existingById.get(skillId), installationId, readRef, now);
+                    if (synced === 'skip')
+                        continue;
+                    // 'kept'/'stale' (both keep a prior row) and 'upserted' all survive the tombstone
+                    // sweep — a transient failure must never retire an existing skill.
+                    liveIds.add(skillId);
+                    if (synced === 'upserted')
+                        upserted++;
+                    else
+                        unchanged++;
+                    // A detected-but-unapplied change leaves us not caught up to the head commit.
+                    if (synced === 'stale')
+                        incomplete = true;
+                }
+                return { liveIds, upserted, unchanged, incomplete };
+            },
+            tombstone: (s, now) => this.deps.accountSkillRepository.softDelete(s.accountId, s.skillId, now),
+            updateSyncState: (commit, now) => this.deps.skillSourceRepository.updateSyncState(source.id, commit, now),
+            invalidate: () => this.deps.invalidateCatalog?.(accountId) ?? Promise.resolve(),
+        });
+    }
+    /** Lightweight "check for changes": one head-commit read compared to the last sync. */
+    async status(accountId, sourceId) {
+        const source = await this.require(accountId, sourceId);
+        const installationId = await this.requireInstallation(source);
+        return probeRepoSourceStatus({ source, installationId, githubClient: this.deps.githubClient });
+    }
+    // --- internals ----------------------------------------------------------
+    async require(accountId, sourceId) {
+        const source = assertFound(await this.deps.skillSourceRepository.get(sourceId), 'SkillSource', sourceId);
+        // The route gate only authorizes the addressed account, so the record must belong
+        // to it; 404 hides other accounts' sources entirely.
+        if (source.accountId !== accountId)
+            throw new NotFoundError('SkillSource', sourceId);
+        if (source.deletedAt !== null)
+            throw new NotFoundError('SkillSource', sourceId);
+        return source;
+    }
+    async requireInstallation(source) {
+        const installationId = await this.deps.resolveInstallationId(source.accountId);
+        if (installationId === null) {
+            throw new ValidationError('No GitHub installation is available for this account; connect GitHub before syncing a skill source');
+        }
+        return installationId;
+    }
+    listDir(source, installationId, path, readRef) {
+        return this.deps.githubClient.listDirectory(installationId, { owner: source.repoOwner, repo: source.repoName }, path, readRef);
+    }
+    /**
+     * Reconcile one `<skill>/` directory:
+     * - 'skip' — not a skill (no `SKILL.md`), or unreadable/unparseable with NO prior row.
+     * - 'kept' — nothing changed; the prior row is current and untouched.
+     * - 'stale' — a change WAS detected but couldn't be applied this round (manifest read
+     *   back as a 404/non-file, or parsed empty) so the prior row is kept alive rather than
+     *   retired. Signals the caller to leave the source pin behind and retry next sync.
+     * - 'upserted' — the manifest or its resource manifest moved and was written.
+     */
+    async syncSkillDir(source, dirName, dirPath, skillId, prior, installationId, readRef, now) {
+        const entries = await this.listDir(source, installationId, dirPath, readRef);
+        const manifest = entries.find((e) => e.type === 'file' && isSkillManifest(e.name));
+        if (!manifest)
+            return 'skip'; // not a skill directory (SKILL.md removed → prior tombstoned)
+        const resources = entries
+            .filter((e) => e.type === 'file' && !isSkillManifest(e.name))
+            .map((e) => ({ path: e.path, sha: e.sha, size: e.size ?? 0 }))
+            .sort((a, b) => a.path.localeCompare(b.path));
+        // Fast path: the SKILL.md blob sha is unchanged AND the resource manifest matches,
+        // so nothing in this skill changed — keep the prior row untouched.
+        if (prior && prior.sourceSha === manifest.sha && sameResources(prior.resources, resources)) {
+            return 'kept';
+        }
+        // Resource-only change: SKILL.md is unchanged but a sibling resource moved. The
+        // manifest content (name/description/instructions) is identical, so refresh only the
+        // resource manifest + pinned commit without re-fetching the body.
+        if (prior && prior.sourceSha === manifest.sha) {
+            await this.deps.accountSkillRepository.upsert({
+                ...prior,
+                resources,
+                pinnedCommit: readRef,
+                updatedAt: now,
+                deletedAt: null,
+            });
+            return 'upserted';
+        }
+        const file = await this.deps.githubClient.getFileContent(installationId, { owner: source.repoOwner, repo: source.repoName }, manifest.path, readRef);
+        // Unreadable / unparseable this round: keep a prior skill alive rather than retiring
+        // it over a transient read or an in-progress edit; with no prior there's nothing to keep.
+        // Either way a change was detected (the manifest sha moved) but not applied, so report
+        // 'stale' so the source pin is NOT advanced and the next sync re-reads.
+        if (!file)
+            return prior ? 'stale' : 'skip';
+        const parsed = parseSkillManifest(dirName, file.content);
+        if (!parsed)
+            return prior ? 'stale' : 'skip';
+        await this.deps.accountSkillRepository.upsert({
+            skillId,
+            accountId: source.accountId,
+            name: parsed.name,
+            description: parsed.description,
+            instructions: parsed.instructions,
+            resources,
+            sourceId: source.id,
+            sourcePath: manifest.path,
+            sourceSha: file.sha,
+            pinnedCommit: readRef,
+            createdAt: prior?.createdAt ?? now,
+            updatedAt: now,
+            deletedAt: null,
+        });
+        return 'upserted';
+    }
+}
+function sameResources(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].path !== b[i].path || a[i].sha !== b[i].sha)
+            return false;
+    }
+    return true;
+}
+function toWire(record) {
+    return {
+        id: record.id,
+        accountId: record.accountId,
+        repoOwner: record.repoOwner,
+        repoName: record.repoName,
+        gitRef: record.gitRef,
+        dirPath: record.dirPath,
+        lastSyncedCommit: record.lastSyncedCommit,
+        lastSyncedAt: record.lastSyncedAt,
+        createdAt: record.createdAt,
+    };
+}
+//# sourceMappingURL=SkillSourceService.js.map

package/dist/skillLibrary/SkillSourceService.js.map

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

package/dist/skillLibrary/skill-source.logic.d.ts

@@ -0,0 +1,21 @@
+/** A skill parsed from a `SKILL.md` manifest's frontmatter + body. */
+export interface ParsedSkillManifest {
+    name: string;
+    description: string;
+    /** The procedural instructions (the markdown body). */
+    instructions: string;
+}
+/** Slug a skill DIRECTORY name into a stable, id-safe token (`Bug Triage` → `bug-triage`). */
+export declare function slugFromDirName(dirName: string): string;
+/** Whether a directory listing entry is a `SKILL.md` manifest (case-insensitive). */
+export declare function isSkillManifest(name: string): boolean;
+/**
+ * Parse a `SKILL.md` file. Frontmatter carries `name` + `description`; the markdown
+ * body is the instructions. Tolerant, mirroring the fragment parser: a missing name
+ * defaults to a humanised directory name and a missing description to the first body
+ * line, so a sparse manifest still imports. Returns null only when there is no usable
+ * body at all — an empty `SKILL.md` is not a skill, and returning null keeps the prior
+ * synced row alive rather than retiring a skill over an in-progress edit.
+ */
+export declare function parseSkillManifest(dirName: string, content: string): ParsedSkillManifest | null;
+//# sourceMappingURL=skill-source.logic.d.ts.map

package/dist/skillLibrary/skill-source.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-source.logic.d.ts","sourceRoot":"","sources":["../../src/skillLibrary/skill-source.logic.ts"],"names":[],"mappings":"AAQA,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAQ/F"}

package/dist/skillLibrary/skill-source.logic.js

@@ -0,0 +1,43 @@
+import { parseSimpleYaml, splitFrontmatter, str } from '../repoSourceSync/frontmatter.js';
+/** Slug a skill DIRECTORY name into a stable, id-safe token (`Bug Triage` → `bug-triage`). */
+export function slugFromDirName(dirName) {
+    return (dirName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'skill');
+}
+/** Whether a directory listing entry is a `SKILL.md` manifest (case-insensitive). */
+export function isSkillManifest(name) {
+    return /^skill\.md$/i.test(name);
+}
+/**
+ * Parse a `SKILL.md` file. Frontmatter carries `name` + `description`; the markdown
+ * body is the instructions. Tolerant, mirroring the fragment parser: a missing name
+ * defaults to a humanised directory name and a missing description to the first body
+ * line, so a sparse manifest still imports. Returns null only when there is no usable
+ * body at all — an empty `SKILL.md` is not a skill, and returning null keeps the prior
+ * synced row alive rather than retiring a skill over an in-progress edit.
+ */
+export function parseSkillManifest(dirName, content) {
+    const { frontmatter, body } = splitFrontmatter(content);
+    const fm = parseSimpleYaml(frontmatter);
+    const instructions = body.trim();
+    if (!instructions)
+        return null;
+    const name = str(fm.name) ?? humanise(dirName);
+    const description = str(fm.description) ?? firstLine(instructions) ?? name;
+    return { name, description, instructions };
+}
+// --- internals ------------------------------------------------------------
+function firstLine(body) {
+    const line = body
+        .split(/\r?\n/)
+        .map((l) => l.replace(/^[#>\-*\s]+/, '').trim())
+        .find((l) => l.length > 0);
+    return line ? line.slice(0, 200) : undefined;
+}
+function humanise(dirName) {
+    const stem = dirName.replace(/[-_]+/g, ' ').trim();
+    return stem ? stem.charAt(0).toUpperCase() + stem.slice(1) : 'Skill';
+}
+//# sourceMappingURL=skill-source.logic.js.map

package/dist/skillLibrary/skill-source.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-source.logic.js","sourceRoot":"","sources":["../../src/skillLibrary/skill-source.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,kCAAkC,CAAA;AAgBzF,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,CACL,OAAO;SACJ,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CACtC,CAAA;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,OAAe;IACjE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACvD,MAAM,EAAE,GAAG,eAAe,CAAC,WAAW,CAAC,CAAA;IACvC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;IAChC,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAA;IAC9B,MAAM,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC9C,MAAM,WAAW,GAAG,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC,YAAY,CAAC,IAAI,IAAI,CAAA;IAC1E,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,EAAE,CAAA;AAC5C,CAAC;AAED,6EAA6E;AAE7E,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,IAAI,GAAG,IAAI;SACd,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;SAC/C,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC5B,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9C,CAAC;AAED,SAAS,QAAQ,CAAC,OAAe;IAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;IAClD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;AACtE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/agents",
-  "version": "0.59.2",
+  "version": "0.61.0",
   "description": "Agent catalog, routing, prompts and fragment library for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -31,14 +31,14 @@
     "ai": "^6.0.224",
     "handlebars": "^4.7.9",
     "valibot": "^1.4.2",
-    "@cat-factory/contracts": "0.135.0",
-    "@cat-factory/kernel": "0.129.2",
-    "@cat-factory/prompt-fragments": "0.13.24"
+    "@cat-factory/contracts": "0.137.0",
+    "@cat-factory/kernel": "0.131.0",
+    "@cat-factory/prompt-fragments": "0.13.26"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/caching": "0.8.7"
+    "@cat-factory/caching": "0.9.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json",