@clossys/launcher 0.1.2 → 0.1.5

package/src/skills.ts

@@ -0,0 +1,120 @@
+import { dirname, join, resolve, sep } from "node:path";
+import type { WorkspaceHost } from "./types.js";
+
+export interface SkillCompositionResult {
+  readonly composed: readonly string[];
+  readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+}
+
+export interface ComposeSkillsOptions {
+  readonly skillCatalogueRoot?: string;
+  readonly launcherPackageRoot: string;
+}
+
+const DISCOVERY_PREFIXES = [".cursor/skills", ".claude/skills"] as const;
+const AGENTS_SKILLS_REL = join(".agents", "skills");
+
+function containedPath(root: string, relativePath: string): string {
+  const resolved = resolve(root, relativePath);
+  const prefix = root.endsWith(sep) ? root : `${root}${sep}`;
+  if (resolved !== root && !resolved.startsWith(prefix)) {
+    throw new Error(`refusing to write outside the workspace directory: ${relativePath}`);
+  }
+  return resolved;
+}
+
+function skillSourceCandidates(packageDir: string, options: ComposeSkillsOptions): string[] {
+  const paths: string[] = [];
+  if (options.skillCatalogueRoot) {
+    paths.push(join(options.skillCatalogueRoot, packageDir, "SKILL.md"));
+  }
+  paths.push(join(options.launcherPackageRoot, "skill-catalogue", packageDir, "SKILL.md"));
+  paths.push(join(options.launcherPackageRoot, "..", packageDir, "skill", "SKILL.md"));
+  return paths;
+}
+
+function readSkillBody(host: WorkspaceHost, packageDir: string, options: ComposeSkillsOptions): string | null {
+  for (const path of skillSourceCandidates(packageDir, options)) {
+    const body = host.readText(path);
+    if (body !== null) return body;
+  }
+  return null;
+}
+
+/** Package directory names that have a resolvable skill source in the catalogue or monorepo. */
+export function listSkillPackageCandidates(host: WorkspaceHost, options: ComposeSkillsOptions): string[] {
+  const names = new Set<string>();
+  const considerRoot = (root: string | undefined): void => {
+    if (root === undefined || !host.isDirectory(root)) return;
+    for (const name of host.readDir(root)) {
+      if (name.startsWith(".")) continue;
+      const skillPath = join(root, name, "SKILL.md");
+      if (host.readText(skillPath) !== null) names.add(name);
+    }
+  };
+  considerRoot(options.skillCatalogueRoot);
+  considerRoot(join(options.launcherPackageRoot, "skill-catalogue"));
+  const packagesSibling = join(options.launcherPackageRoot, "..");
+  if (host.isDirectory(packagesSibling)) {
+    for (const name of host.readDir(packagesSibling)) {
+      if (name.startsWith(".")) continue;
+      const skillPath = join(packagesSibling, name, "skill", "SKILL.md");
+      if (host.readText(skillPath) !== null) names.add(name);
+    }
+  }
+  return [...names].sort((a, b) => a.localeCompare(b));
+}
+
+function writeAgentsSkill(host: WorkspaceHost, directory: string, packageDir: string, body: string): void {
+  const relativeDir = join(AGENTS_SKILLS_REL, `clossys-${packageDir}`);
+  const skillRel = join(relativeDir, "SKILL.md");
+  const target = containedPath(directory, skillRel);
+  host.mkdirp(dirname(target));
+  host.writeText(target, body.endsWith("\n") ? body : `${body}\n`);
+}
+
+function writeDiscoveryLink(host: WorkspaceHost, directory: string, packageDir: string, skillBody: string): void {
+  const agentsDirRel = join(AGENTS_SKILLS_REL, `clossys-${packageDir}`);
+  const linkTarget = join("..", "..", agentsDirRel);
+  for (const prefix of DISCOVERY_PREFIXES) {
+    const prefixPath = containedPath(directory, prefix);
+    // A directory-symlink onto `.agents/skills` already exposes every composed
+    // skill. Writing a nested `.claude/skills/clossys-<pkg>` link follows that
+    // symlink and replaces the just-written SKILL.md with a circular link.
+    if (host.isSymlink(prefixPath)) continue;
+    const linkRel = join(prefix, `clossys-${packageDir}`);
+    const linkPath = containedPath(directory, linkRel);
+    host.mkdirp(dirname(linkPath));
+    try {
+      host.symlink(linkTarget, linkPath);
+    } catch {
+      const fallbackDir = containedPath(directory, join(linkRel, "SKILL.md"));
+      host.mkdirp(dirname(fallbackDir));
+      host.writeText(fallbackDir, skillBody.endsWith("\n") ? skillBody : `${skillBody}\n`);
+    }
+  }
+}
+
+/**
+ * Writes `.agents/skills/clossys-<pkg>/SKILL.md` and host discovery links for every
+ * catalogue package. Missing sources are skipped with notes; the hub apply continues.
+ */
+export function composeSkills(
+  host: WorkspaceHost,
+  directory: string,
+  options: ComposeSkillsOptions,
+): SkillCompositionResult {
+  const composed: string[] = [];
+  const skipped: { packageDir: string; note: string }[] = [];
+  for (const packageDir of listSkillPackageCandidates(host, options)) {
+    const body = readSkillBody(host, packageDir, options);
+    if (body === null) {
+      skipped.push({ packageDir, note: "skill source missing at apply time" });
+      continue;
+    }
+    writeAgentsSkill(host, directory, packageDir, body);
+    writeDiscoveryLink(host, directory, packageDir, body);
+    composed.push(packageDir);
+  }
+  return { composed, skipped };
+}

package/src/types.ts

@@ -16,9 +16,13 @@ export interface WorkspaceHost {
   now(): string;
   exists(path: string): boolean;
   isDirectory(path: string): boolean;
+  /** True when path exists and is a symlink (lstat; does not follow). Missing path is false. */
+  isSymlink(path: string): boolean;
   readText(path: string): string | null;
   writeText(path: string, contents: string): void;
   mkdirp(path: string): void;
+  /** Creates a relative symlink at linkPath pointing at relativeTarget (directory link). */
+  symlink(relativeTarget: string, linkPath: string): void;
   readDir(path: string): string[];
   run(command: string, args: readonly string[], options?: { cwd?: string }): CommandResult;
   prompt(message: string, choices: readonly string[]): string | null;
@@ -80,6 +84,18 @@ export interface HubHealthReport {
   readonly extraClossys: readonly string[];
   readonly pinFindings: readonly PinFinding[];
   readonly degraded: boolean;
+  readonly skillComposition?: {
+    readonly composed: readonly string[];
+    readonly skipped: readonly { readonly packageDir: string; readonly note: string }[];
+    readonly rosterTargets?: readonly string[];
+    readonly rosterSkipped?: readonly { readonly inventoryId: string; readonly note: string }[];
+  };
+}
+
+/** Optional paths for skill composition during apply. */
+export interface ApplyWorkspaceOptions {
+  readonly skillCatalogueRoot?: string;
+  readonly launcherPackageRoot?: string;
 }
 
 export interface CwdObservation {