@clossys/launcher 0.1.5 → 0.3.0

package/src/product-repository.ts

@@ -0,0 +1,73 @@
+import { join } from "node:path";
+import type { WorkspaceHost } from "./types.js";
+
+/**
+ * One check from this repository's own docs/contracts/product-repository-layout.json `cloudSessionBootstrap` list (that contract file does not ship in the published package).
+ * Read-only: verifies a product repository has what a cloud agent session
+ * (browser plus GitHub only, no local setup) needs to install and run the
+ * team, without foundry's own heavy governance gates.
+ */
+export interface CloudBootstrapCheck {
+  readonly id: "package-manifest" | "agents-pointer" | "hub-marker";
+  readonly label: string;
+  readonly satisfied: boolean;
+  readonly note?: string;
+}
+
+export interface CloudBootstrapReport {
+  readonly schemaVersion: 1;
+  readonly checks: readonly CloudBootstrapCheck[];
+  readonly ready: boolean;
+}
+
+const PACKAGE_JSON_REL = "package.json";
+const PACKAGE_LOCK_REL = "package-lock.json";
+const AGENTS_MD_REL = "AGENTS.md";
+const HUB_MARKER_REL = join("clossys", ".state", "workspace.json");
+
+/**
+ * Runs the three product-repository-layout.json cloudSessionBootstrap checks
+ * against `directory`. Never mutates anything, never runs `npm ci` itself
+ * -- it checks that the manifest and lockfile are BOTH present, which is
+ * the precondition a real `npm ci` needs, not a substitute for running it.
+ */
+export function checkCloudSessionBootstrap(host: WorkspaceHost, directory: string): CloudBootstrapReport {
+  const hasManifest = host.exists(join(directory, PACKAGE_JSON_REL));
+  const hasLock = host.exists(join(directory, PACKAGE_LOCK_REL));
+  const manifestCheck: CloudBootstrapCheck = {
+    id: "package-manifest",
+    label: "package.json and package-lock.json are both present",
+    satisfied: hasManifest && hasLock,
+    ...(hasManifest && hasLock
+      ? {}
+      : {
+          note: !hasManifest && !hasLock
+            ? "Neither package.json nor package-lock.json exists yet."
+            : !hasManifest
+              ? "package-lock.json exists but package.json does not."
+              : "package.json exists but package-lock.json does not -- npm ci needs both.",
+        }),
+  };
+
+  const agentsRaw = host.readText(join(directory, AGENTS_MD_REL));
+  const agentsPointsAtClossys = agentsRaw !== null && agentsRaw.includes("clossys/");
+  const agentsCheck: CloudBootstrapCheck = {
+    id: "agents-pointer",
+    label: "AGENTS.md exists at the repository root and points at clossys/",
+    satisfied: agentsPointsAtClossys,
+    ...(agentsPointsAtClossys
+      ? {}
+      : { note: agentsRaw === null ? "AGENTS.md does not exist at the repository root." : "AGENTS.md exists but does not mention clossys/." }),
+  };
+
+  const hasHubMarker = host.exists(join(directory, HUB_MARKER_REL));
+  const markerCheck: CloudBootstrapCheck = {
+    id: "hub-marker",
+    label: "clossys/.state/workspace.json (the hub marker) is present",
+    satisfied: hasHubMarker,
+    ...(hasHubMarker ? {} : { note: "clossys/.state/workspace.json does not exist yet." }),
+  };
+
+  const checks = [manifestCheck, agentsCheck, markerCheck];
+  return { schemaVersion: 1, checks, ready: checks.every((check) => check.satisfied) };
+}

package/src/skills.ts

@@ -1,18 +1,27 @@
 import { dirname, join, resolve, sep } from "node:path";
-import type { WorkspaceHost } from "./types.js";
+import { extractContractBlock, injectContract } from "./contract.js";
+import { parseSkillManifest, readInstalledVersion, serializeSkillManifest, sha256Hex } from "./manifest.js";
+import type { SkillManifestEntry, WorkspaceHost } from "./types.js";
 
 export interface SkillCompositionResult {
   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 }[];
+  /** Skills pruned this run: present in the directory's previous manifest, absent from this run's composed set. */
+  readonly retired: readonly string[];
 }
 
 export interface ComposeSkillsOptions {
   readonly skillCatalogueRoot?: string;
   readonly launcherPackageRoot: string;
+  /** Overrides where the packed conversation contract is read from (tests). */
+  readonly contractPath?: string;
 }
 
-const DISCOVERY_PREFIXES = [".cursor/skills", ".claude/skills"] as const;
+export const DISCOVERY_PREFIXES = [".cursor/skills", ".claude/skills"] as const;
 const AGENTS_SKILLS_REL = join(".agents", "skills");
+export const SKILLS_MANIFEST_REL = join("clossys", ".state", "skills.json");
 
 function containedPath(root: string, relativePath: string): string {
   const resolved = resolve(root, relativePath);
@@ -33,14 +42,63 @@ function skillSourceCandidates(packageDir: string, options: ComposeSkillsOptions
   return paths;
 }
 
-function readSkillBody(host: WorkspaceHost, packageDir: string, options: ComposeSkillsOptions): string | null {
+function installedSkillPath(composeTargetDirectory: string, packageDir: string): string {
+  return join(composeTargetDirectory, "node_modules", "@clossys", packageDir, "skill", "SKILL.md");
+}
+
+function readSkillBody(
+  host: WorkspaceHost,
+  packageDir: string,
+  options: ComposeSkillsOptions,
+  composeTargetDirectory: string,
+): { body: string; source: "installed" | "catalogue" } | null {
+  const installed = host.readText(installedSkillPath(composeTargetDirectory, packageDir));
+  if (installed !== null) return { body: installed, source: "installed" };
   for (const path of skillSourceCandidates(packageDir, options)) {
     const body = host.readText(path);
-    if (body !== null) return body;
+    if (body !== null) return { body, source: "catalogue" };
+  }
+  return null;
+}
+
+function contractSourceCandidates(options: ComposeSkillsOptions): string[] {
+  const paths: string[] = [];
+  if (options.contractPath) paths.push(options.contractPath);
+  paths.push(join(options.launcherPackageRoot, "contracts", "conversation-contract.md"));
+  // Monorepo fallback so tests and dev runs work without a prior `npm run build` pack step.
+  paths.push(join(options.launcherPackageRoot, "..", "..", "docs", "contracts", "conversation-contract.md"));
+  return paths;
+}
+
+/** Reads and extracts the shared conversation contract block. Returns null when no source resolves. */
+function readContractBlock(host: WorkspaceHost, options: ComposeSkillsOptions): string | null {
+  for (const path of contractSourceCandidates(options)) {
+    const raw = host.readText(path);
+    if (raw === null) continue;
+    try {
+      return extractContractBlock(raw);
+    } catch {
+      continue;
+    }
   }
   return null;
 }
 
+function readLauncherVersion(host: WorkspaceHost, options: ComposeSkillsOptions): string | undefined {
+  const raw = host.readText(join(options.launcherPackageRoot, "package.json"));
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && "version" in parsed) {
+      const version = (parsed as { version?: unknown }).version;
+      if (typeof version === "string" && version.trim() !== "") return version;
+    }
+  } catch {
+    /* unreadable manifest; no version */
+  }
+  return undefined;
+}
+
 /** 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>();
@@ -95,9 +153,27 @@ function writeDiscoveryLink(host: WorkspaceHost, directory: string, packageDir:
   }
 }
 
+/** Removes a composed skill's `.agents/skills/` directory and its host discovery links. Missing paths are no-ops. */
+function removeComposedSkill(host: WorkspaceHost, directory: string, packageDir: string): void {
+  host.remove(containedPath(directory, join(AGENTS_SKILLS_REL, `clossys-${packageDir}`)));
+  for (const prefix of DISCOVERY_PREFIXES) {
+    const prefixPath = containedPath(directory, prefix);
+    if (host.isSymlink(prefixPath)) continue; // shared view onto .agents/skills; already handled above
+    host.remove(containedPath(directory, join(prefix, `clossys-${packageDir}`)));
+  }
+}
+
 /**
  * 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.
+ * catalogue package, with the shared conversation contract (#1182) injected in place
+ * of each skill's own `## How we work together` / `## One question at a time`
+ * sections. Missing sources are skipped with notes; the hub apply continues.
+ *
+ * Also writes `clossys/.state/skills.json` (#1183): source, version, and content
+ * digest per composed skill. A skill named in this directory's *previous* manifest
+ * but not composed this run is retired — its composed output is pruned and it is
+ * dropped from the new manifest. Never touches a skill this directory's manifest
+ * did not itself write.
  */
 export function composeSkills(
   host: WorkspaceHost,
@@ -106,15 +182,44 @@ export function composeSkills(
 ): SkillCompositionResult {
   const composed: string[] = [];
   const skipped: { packageDir: string; note: string }[] = [];
+  const manifestEntries: SkillManifestEntry[] = [];
+  const contractBlock = readContractBlock(host, options);
+  const launcherVersion = readLauncherVersion(host, options);
+
   for (const packageDir of listSkillPackageCandidates(host, options)) {
-    const body = readSkillBody(host, packageDir, options);
-    if (body === null) {
+    const found = readSkillBody(host, packageDir, options, directory);
+    if (found === null) {
       skipped.push({ packageDir, note: "skill source missing at apply time" });
       continue;
     }
+    const body = contractBlock === null ? found.body : injectContract(found.body, contractBlock);
     writeAgentsSkill(host, directory, packageDir, body);
     writeDiscoveryLink(host, directory, packageDir, body);
     composed.push(packageDir);
+    const version = found.source === "installed" ? readInstalledVersion(host, directory, packageDir) : launcherVersion;
+    manifestEntries.push({
+      name: packageDir,
+      source: found.source,
+      sha256: sha256Hex(body.endsWith("\n") ? body : `${body}\n`),
+      ...(version === undefined ? {} : { version }),
+    });
   }
-  return { composed, skipped };
+
+  const previousManifest = parseSkillManifest(host.readText(join(directory, SKILLS_MANIFEST_REL)));
+  const composedSet = new Set(composed);
+  const retired: string[] = [];
+  for (const entry of previousManifest?.skills ?? []) {
+    if (composedSet.has(entry.name)) continue;
+    removeComposedSkill(host, directory, entry.name);
+    retired.push(entry.name);
+  }
+
+  const manifestPath = containedPath(directory, SKILLS_MANIFEST_REL);
+  host.mkdirp(dirname(manifestPath));
+  host.writeText(
+    manifestPath,
+    serializeSkillManifest({ schemaVersion: 1, generatedAt: host.now(), skills: manifestEntries }),
+  );
+
+  return { composed, skipped, retired };
 }

package/src/types.ts

@@ -1,3 +1,6 @@
+import type { DiscoveredHost } from "./hosts.js";
+import type { ExternalInventoryDeclaration, InventoryDriftReport } from "./inventory-adoption.js";
+
 /** Ternary retained by the installed CLI. */
 export type WorkspaceState = "satisfied" | "violated" | "indeterminate";
 
@@ -23,17 +26,52 @@ export interface WorkspaceHost {
   mkdirp(path: string): void;
   /** Creates a relative symlink at linkPath pointing at relativeTarget (directory link). */
   symlink(relativeTarget: string, linkPath: string): void;
+  /** Recursively removes path. A missing path is a no-op, never a throw. */
+  remove(path: string): void;
   readDir(path: string): string[];
   run(command: string, args: readonly string[], options?: { cwd?: string }): CommandResult;
   prompt(message: string, choices: readonly string[]): string | null;
 }
 
-/** On-disk hub marker generated on the consumer hub. Packed template: skeleton/.clossys/workspace.json. */
+/** On-disk hub marker generated on the consumer hub. Packed template: skeleton/clossys/.state/workspace.json. */
 export interface HubDocument {
   readonly schemaVersion: 1;
   readonly kind: "account-hub";
   readonly owner: string;
   readonly repository: string;
+  /** Declares an existing external repository inventory as the source of truth (#1216). Hand-edited by the client; launcher never writes this field. */
+  readonly externalInventory?: ExternalInventoryDeclaration;
+}
+
+/**
+ * Where the hub marker was found relative to the `.clossys/` -> `clossys/.state/`
+ * migration (#1171): `clean` — only the current path. `legacy` — only the old
+ * `.clossys/` path; resume migrates it. `indeterminate` — both paths carry a
+ * parseable marker; launcher never merges them silently and refuses instead.
+ */
+export type HubMigrationState = "clean" | "legacy" | "indeterminate";
+
+/** One skill recorded in `clossys/.state/skills.json` (#1183). */
+export interface SkillManifestEntry {
+  readonly name: string;
+  readonly source: "installed" | "catalogue";
+  readonly version?: string;
+  readonly sha256: string;
+}
+
+/** The `clossys/.state/skills.json` document itself. */
+export interface SkillManifestDocument {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly skills: readonly SkillManifestEntry[];
+}
+
+/** Read-only freshness summary derived from the skills manifest for the health report. */
+export interface SkillsManifestSummary {
+  readonly status: "present" | "missing";
+  readonly total: number;
+  readonly stale: number;
+  readonly retired: number;
 }
 
 export interface InventoryObservation {
@@ -84,18 +122,31 @@ export interface HubHealthReport {
   readonly extraClossys: readonly string[];
   readonly pinFindings: readonly PinFinding[];
   readonly degraded: boolean;
+  /** Coding-agent hosts this apply found already linked for skill discovery here, recorded before compose ran (#1180). Always present after apply. */
+  readonly linkedHosts?: readonly DiscoveredHost[];
+  /** Present only when the hub marker declares an external inventory (#1216) and there is something to say about it (i.e. not "no-external-source"). */
+  readonly inventoryDrift?: InventoryDriftReport;
   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 }[];
+    readonly retired?: readonly string[];
   };
+  /** Present only on the run that performed the `.clossys/` -> `clossys/.state/` migration. */
+  readonly migration?: { readonly status: "migrated"; readonly from: string; readonly to: string };
+  /** Freshness summary derived from `clossys/.state/skills.json`, when present. */
+  readonly skillsManifest?: SkillsManifestSummary;
 }
 
 /** Optional paths for skill composition during apply. */
 export interface ApplyWorkspaceOptions {
   readonly skillCatalogueRoot?: string;
   readonly launcherPackageRoot?: string;
+  /** Overrides where the packed conversation contract is read from (tests). */
+  readonly contractPath?: string;
+  /** Live registry `@clossys/launcher` version, used only to grade catalogue-sourced skill staleness. */
+  readonly liveLauncherVersion?: string;
 }
 
 export interface CwdObservation {
@@ -107,6 +158,8 @@ export interface CwdObservation {
   readonly hub?: HubDocument;
   readonly looksLikeFoundry: boolean;
   readonly inventory?: InventoryObservation;
+  /** Present only when a hub marker was found; absent means neither path has one. */
+  readonly hubMigration?: HubMigrationState;
 }
 
 export interface WorkspaceObservation {
@@ -133,6 +186,10 @@ export interface WorkspacePlanResume {
   readonly repository: string;
   readonly directory: string;
   readonly clone: boolean;
+  /** Live registry Advisor version, when observeWorkspace could read one. Used only to grade health. */
+  readonly advisorVersion?: string;
+  /** Set when the hub marker was found only at the legacy `.clossys/` path; apply migrates it. */
+  readonly migrateFrom?: "legacy";
 }
 
 export interface WorkspacePlanAdopt {