@clossys/launcher 0.1.1 → 0.1.5

package/src/host.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, readSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import type { CommandResult, WorkspaceHost } from "./types.js";
 
 function run(command: string, args: readonly string[], options?: { cwd?: string }): CommandResult {
@@ -43,6 +44,13 @@ export function createNodeHost(cwd = process.cwd(), env: NodeJS.ProcessEnv = pro
     now: () => new Date().toISOString(),
     exists: (path) => existsSync(path),
     isDirectory: (path) => existsSync(path) && statSync(path).isDirectory(),
+    isSymlink: (path) => {
+      try {
+        return lstatSync(path).isSymbolicLink();
+      } catch {
+        return false;
+      }
+    },
     readText: (path) => {
       try {
         return readFileSync(path, "utf8");
@@ -56,6 +64,11 @@ export function createNodeHost(cwd = process.cwd(), env: NodeJS.ProcessEnv = pro
     mkdirp: (path) => {
       mkdirSync(path, { recursive: true });
     },
+    symlink: (relativeTarget, linkPath) => {
+      mkdirSync(dirname(linkPath), { recursive: true });
+      if (existsSync(linkPath)) rmSync(linkPath, { recursive: true, force: true });
+      symlinkSync(relativeTarget, linkPath, "dir");
+    },
     readDir: (path) => readdirSync(path),
     run,
     prompt,

package/src/index.ts

@@ -1,23 +1,33 @@
 /** Consumer-owned workspace hub scaffolder: create, resume, or appoint a GitHub repository. */
 export {
   applyWorkspacePlan,
+  checkInventoryEntries,
   formatHubHealth,
+  hasAdvisorPin,
   inspectInventory,
   isHubDocument,
+  launcherPackageRootFromModule,
   observeWorkspace,
   parseGitHubRemote,
   planWorkspace,
+  readInventoryRepositories,
   reportHubHealth,
   DEFAULT_REPOSITORY_NAME,
   WORKSPACE_INVENTORY_REL,
   WORKSPACE_MARKER_REL,
 } from "./core.js";
 export type {
+  ApplyWorkspaceOptions,
   CommandResult,
   CwdObservation,
+  DependencyBucket,
   HubDocument,
   HubHealthReport,
   InventoryObservation,
+  InventoryValidationEntry,
+  InventoryValidationReport,
+  PinFinding,
+  PinGrade,
   WorkspaceApplyResult,
   WorkspaceDecision,
   WorkspaceHost,

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;
@@ -37,6 +41,34 @@ export interface InventoryObservation {
   readonly count: number;
 }
 
+/** A package.json dependency bucket scanned for the advisor pin. */
+export type DependencyBucket = "dependencies" | "devDependencies" | "optionalDependencies" | "peerDependencies";
+
+/** Staleness verdict for one pinned advisor version against the live registry version. */
+export type PinGrade = "stale" | "current" | "indeterminate";
+
+/** One graded advisor pin in one dependency bucket. */
+export interface PinFinding {
+  readonly bucket: DependencyBucket;
+  readonly pinned: string;
+  readonly grade: PinGrade;
+  readonly note?: string;
+}
+
+/** Verdict for one hub inventory repository id after a read-only existence check. */
+export interface InventoryValidationEntry {
+  readonly id: string;
+  readonly known: boolean | null;
+  readonly note?: string;
+}
+
+/** Read-only validation outcome for hub inventory ids. Never mutates the inventory. */
+export interface InventoryValidationReport {
+  readonly entries: readonly InventoryValidationEntry[];
+  readonly skipped: boolean;
+  readonly note?: string;
+}
+
 /** Read-only pin and inventory report after adopt or resume. Never uninstalls. */
 export interface HubHealthReport {
   readonly marker: "present" | "missing";
@@ -44,10 +76,26 @@ export interface HubHealthReport {
   readonly advisorPin: {
     readonly dependencies?: string;
     readonly devDependencies?: string;
+    readonly optionalDependencies?: string;
+    readonly peerDependencies?: string;
     readonly live?: string;
   };
   readonly dualPin: boolean;
   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 {
@@ -95,6 +143,8 @@ export interface WorkspacePlanAdopt {
   readonly advisorVersion: string;
   /** Absolute path of a populated inventory document to copy. Absent when cwd already has one. */
   readonly inventorySource?: string;
+  /** Merged repository ids (on-disk first, then new ids from --inventory) written when both sources are populated. */
+  readonly mergedInventoryIds?: readonly string[];
 }
 
 export type WorkspacePlan = WorkspacePlanCreate | WorkspacePlanResume | WorkspacePlanAdopt;