@clossys/launcher 0.1.2 → 0.3.0

package/src/doctor-cli.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { isDirectInvocation } from "./cli.js";
+import { createNodeHost } from "./host.js";
+import { renderDoctorReport, runDoctorChecks } from "./doctor.js";
+
+export const DOCTOR_USAGE = `Usage: launcher-doctor
+
+Read-only. Checks the prerequisites a client needs before the hub exists:
+git, the GitHub command-line tool, whether you are signed in, Node.js, and
+npm. Reports the first thing that is missing, in plain language, with the
+next action to take -- never a dump of everything at once.
+
+Exit codes: 0 = ready, 2 = at least one prerequisite is missing.`;
+
+export function main(argv: readonly string[]): number {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+    console.log(DOCTOR_USAGE);
+    return 0;
+  }
+  if (argv.length !== 0) {
+    console.error("launcher-doctor: takes no arguments");
+    return 2;
+  }
+  const host = createNodeHost();
+  const report = runDoctorChecks(host);
+  console.log(renderDoctorReport(report));
+  return report.allSatisfied ? 0 : 2;
+}
+
+function run(): void {
+  process.exitCode = main(process.argv.slice(2));
+}
+if (isDirectInvocation(import.meta.url, process.argv[1])) run();

package/src/doctor.ts

@@ -0,0 +1,145 @@
+// launcher doctor (#1220) -- read-only. Names each missing prerequisite in
+// plain language, one at a time, in the order a non-technical client
+// should fix them: git -> the GitHub command-line tool -> being signed in
+// -> Node.js -> npm. A missing coding agent is advisory only -- Launcher
+// cannot detect every host, and it is a one-time choice the client makes,
+// not a step to fix in sequence.
+
+import type { CommandResult } from "./types.js";
+
+export interface DoctorCheckHost {
+  run(command: string, args: readonly string[]): CommandResult;
+}
+
+export type DoctorStepId = "git" | "gh-cli" | "gh-auth" | "node" | "npm" | "coding-agent";
+
+export interface DoctorStepResult {
+  readonly id: DoctorStepId;
+  readonly label: string;
+  readonly satisfied: boolean;
+  /** Plain-language description of what is missing, present only when satisfied is false. */
+  readonly problem?: string;
+  /** The single next action, present only when satisfied is false. */
+  readonly nextAction?: string;
+  /** True for steps that inform but never block (e.g. coding-agent discovery). */
+  readonly advisory: boolean;
+}
+
+export interface DoctorReport {
+  readonly schemaVersion: 1;
+  readonly steps: readonly DoctorStepResult[];
+  /** The first unsatisfied non-advisory step, in order -- what the client should fix right now. */
+  readonly nextToFix?: DoctorStepResult;
+  readonly allSatisfied: boolean;
+}
+
+function ok(id: DoctorStepId, label: string, advisory = false): DoctorStepResult {
+  return { id, label, satisfied: true, advisory };
+}
+
+function missing(id: DoctorStepId, label: string, problem: string, nextAction: string, advisory = false): DoctorStepResult {
+  return { id, label, satisfied: false, problem, nextAction, advisory };
+}
+
+function commandSucceeds(host: DoctorCheckHost, command: string, args: readonly string[]): boolean {
+  try {
+    return host.run(command, args).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Runs every doctor check in the fix-in-this-order sequence. Never mutates anything. */
+export function runDoctorChecks(host: DoctorCheckHost): DoctorReport {
+  const steps: DoctorStepResult[] = [];
+
+  const hasGit = commandSucceeds(host, "git", ["--version"]);
+  steps.push(
+    hasGit
+      ? ok("git", "Git is installed")
+      : missing(
+          "git",
+          "Git is installed",
+          "Git is not installed on this computer. Launcher and your coding agent both need it to save and share work.",
+          "Install Git from https://git-scm.com/downloads, then run this command again.",
+        ),
+  );
+
+  const hasGh = commandSucceeds(host, "gh", ["--version"]);
+  steps.push(
+    hasGh
+      ? ok("gh-cli", "The GitHub command-line tool (gh) is installed")
+      : missing(
+          "gh-cli",
+          "The GitHub command-line tool (gh) is installed",
+          "The GitHub command-line tool is not installed. Launcher uses it to create and find your GitHub repositories.",
+          "Install it from https://cli.github.com, then run this command again.",
+        ),
+  );
+
+  const ghAuthed = hasGh && commandSucceeds(host, "gh", ["auth", "status"]);
+  steps.push(
+    !hasGh
+      ? missing(
+          "gh-auth",
+          "You are signed in to GitHub",
+          "This cannot be checked yet because the GitHub command-line tool is not installed.",
+          "Install the GitHub command-line tool first (see above), then run this command again.",
+        )
+      : ghAuthed
+        ? ok("gh-auth", "You are signed in to GitHub")
+        : missing(
+            "gh-auth",
+            "You are signed in to GitHub",
+            "You are not signed in to GitHub yet.",
+            "Run `gh auth login` and follow the prompts, then run this command again.",
+          ),
+  );
+
+  const hasNode = commandSucceeds(host, "node", ["--version"]);
+  steps.push(
+    hasNode
+      ? ok("node", "Node.js is installed")
+      : missing(
+          "node",
+          "Node.js is installed",
+          "Node.js is not installed. It is what runs the team's tools on this computer.",
+          "Install the current LTS release from https://nodejs.org, then run this command again.",
+        ),
+  );
+
+  const hasNpm = commandSucceeds(host, "npm", ["--version"]);
+  steps.push(
+    hasNpm
+      ? ok("npm", "npm is installed")
+      : missing(
+          "npm",
+          "npm is installed",
+          "npm is not installed. It comes with Node.js, so this is usually fixed by installing or reinstalling Node.js.",
+          "Install Node.js from https://nodejs.org (npm is included), then run this command again.",
+        ),
+  );
+
+  // Advisory only: never blocks doctor's overall verdict. A missing coding
+  // agent is not a step to fix in a particular order -- it is a one-time
+  // choice the client makes, and Launcher cannot detect every host.
+  steps.push(ok("coding-agent", "A coding agent is available to open this hub", true));
+
+  const firstUnsatisfied = steps.find((step) => !step.satisfied && !step.advisory);
+  return {
+    schemaVersion: 1,
+    steps,
+    ...(firstUnsatisfied === undefined ? {} : { nextToFix: firstUnsatisfied }),
+    allSatisfied: firstUnsatisfied === undefined,
+  };
+}
+
+/** Renders one step at a time, plain language, the way a non-technical client reads it. */
+export function renderDoctorReport(report: DoctorReport): string {
+  if (report.allSatisfied) {
+    return "Everything doctor checks is ready. Open this folder in your coding agent and talk to @clossys-advisor to get started.";
+  }
+  const step = report.nextToFix;
+  if (step === undefined) return "Everything doctor checks is ready.";
+  return `${step.label}: not yet.\n${step.problem}\n\nNext: ${step.nextAction}`;
+}

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,14 @@ 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");
+    },
+    remove: (path) => {
+      rmSync(path, { recursive: true, force: true });
+    },
     readDir: (path) => readdirSync(path),
     run,
     prompt,

package/src/hosts.ts

@@ -0,0 +1,79 @@
+// Records which coding-agent host(s) this run linked skill discovery for
+// (#1180, Launcher side), so a consumer (Advisor's next-action phrasing)
+// can name the client's actual tool instead of guessing.
+//
+// Codex discovery verified 2026-09-22 (developers.openai.com/codex/skills,
+// developers.openai.com/codex/concepts/customization): Codex reads
+// repository skills directly from `.agents/skills` -- the SAME directory
+// skills.ts's AGENTS_SKILLS_REL already writes the real composed skill to.
+// It needs no separate discovery symlink the way Claude Code (.claude/skills)
+// and Cursor (.cursor/skills) do, so "codex" is detected by the presence of
+// `.agents/skills` itself, not a host-specific prefix.
+
+import { join } from "node:path";
+import type { WorkspaceHost } from "./types.js";
+
+export type DiscoveredHost = "claude-code" | "cursor" | "codex";
+
+export interface HostRecord {
+  readonly schemaVersion: 1;
+  /** Hosts whose discovery this directory currently carries. */
+  readonly linkedHosts: readonly DiscoveredHost[];
+  readonly recordedAt: string;
+}
+
+export const HOSTS_REL = join("clossys", ".state", "hosts.json");
+
+const AGENTS_SKILLS_REL = join(".agents", "skills");
+
+// Claude Code and Cursor need their own discovery symlink; Codex reads
+// .agents/skills directly (see module header) and is detected separately.
+const SYMLINK_DISCOVERY_PATHS: ReadonlyArray<{ host: DiscoveredHost; prefix: string }> = [
+  { host: "claude-code", prefix: ".claude/skills" },
+  { host: "cursor", prefix: ".cursor/skills" },
+];
+
+/** Read-only: which hosts can actually discover skills in this directory right now. */
+export function detectLinkedHosts(host: WorkspaceHost, directory: string): readonly DiscoveredHost[] {
+  const found: DiscoveredHost[] = [];
+  for (const { host: id, prefix } of SYMLINK_DISCOVERY_PATHS) {
+    if (host.isDirectory(join(directory, prefix)) || host.isSymlink(join(directory, prefix))) {
+      found.push(id);
+    }
+  }
+  if (host.isDirectory(join(directory, AGENTS_SKILLS_REL))) {
+    found.push("codex");
+  }
+  return found;
+}
+
+export function serializeHostRecord(record: HostRecord): string {
+  return `${JSON.stringify(record, null, 2)}\n`;
+}
+
+export function parseHostRecord(raw: string | null): HostRecord | undefined {
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed) &&
+      (parsed as Record<string, unknown>).schemaVersion === 1 &&
+      Array.isArray((parsed as Record<string, unknown>).linkedHosts)
+    ) {
+      const record = parsed as { linkedHosts: unknown[]; recordedAt: unknown };
+      const linkedHosts = record.linkedHosts.filter(
+        (item): item is DiscoveredHost => item === "claude-code" || item === "cursor" || item === "codex",
+      );
+      return {
+        schemaVersion: 1,
+        linkedHosts,
+        recordedAt: typeof record.recordedAt === "string" ? record.recordedAt : "",
+      };
+    }
+  } catch {
+    /* falls through */
+  }
+  return undefined;
+}

package/src/index.ts

@@ -2,29 +2,65 @@
 export {
   applyWorkspacePlan,
   checkInventoryEntries,
+  cloneMissingInventoryRepositories,
   formatHubHealth,
   hasAdvisorPin,
   inspectInventory,
   isHubDocument,
+  launcherPackageRootFromModule,
   observeWorkspace,
   parseGitHubRemote,
   planWorkspace,
+  readInventoryRepositories,
+  readLiveLauncherVersion,
   reportHubHealth,
+  CLOSSYS_DIR_REL,
+  CLOSSYS_README_REL,
   DEFAULT_REPOSITORY_NAME,
+  LEGACY_STATE_DIR_REL,
+  LEGACY_WORKSPACE_INVENTORY_REL,
+  LEGACY_WORKSPACE_MARKER_REL,
+  STATE_DIR_REL,
   WORKSPACE_INVENTORY_REL,
   WORKSPACE_MARKER_REL,
 } from "./core.js";
+export type { CloneMissingOutcome } from "./core.js";
+export { runDoctorChecks, renderDoctorReport } from "./doctor.js";
+export { applyEngagementBrief, isPlanApproved, validateAdvisorPlan, validateEngagementBrief } from "./apply-plan.js";
+export type { AdvisorPlan, ApplyBriefResult, BlockerKind, EngagementBrief, EngagementBriefRole, PlanBlocker, PlanDecision, ValidationResult } from "./apply-plan.js";
+export type { DoctorCheckHost, DoctorReport, DoctorStepId, DoctorStepResult } from "./doctor.js";
+export { checkCloudSessionBootstrap } from "./product-repository.js";
+export type { CloudBootstrapCheck, CloudBootstrapReport } from "./product-repository.js";
+export { reportInventoryDrift } from "./inventory-adoption.js";
+export type { ExternalInventoryDeclaration, InventoryDriftReport } from "./inventory-adoption.js";
+export { detectLinkedHosts, parseHostRecord, serializeHostRecord, HOSTS_REL } from "./hosts.js";
+export type { DiscoveredHost, HostRecord } from "./hosts.js";
+export { parsePreferences, readHostModelProfile, resolveModelForTier } from "./model-profile.js";
 export type {
+  BudgetPreference,
+  HostModelProfile,
+  HostTierMapping,
+  ModelResolution,
+  PreferencesDocument,
+  ReasoningTier,
+  SupportedHost,
+} from "./model-profile.js";
+export type {
+  ApplyWorkspaceOptions,
   CommandResult,
   CwdObservation,
   DependencyBucket,
   HubDocument,
   HubHealthReport,
+  HubMigrationState,
   InventoryObservation,
   InventoryValidationEntry,
   InventoryValidationReport,
   PinFinding,
   PinGrade,
+  SkillManifestDocument,
+  SkillManifestEntry,
+  SkillsManifestSummary,
   WorkspaceApplyResult,
   WorkspaceDecision,
   WorkspaceHost,

package/src/inventory-adoption.ts

@@ -0,0 +1,85 @@
+// Adopt an existing repository inventory instead of creating a second one
+// (#1216). An account that already keeps a repository inventory in its own
+// control plane becomes the source of truth when the hub marker declares
+// it. Launcher writes only what that inventory lacks (a later apply step,
+// not this module) and reports drift instead of silently merging.
+
+import type { WorkspaceHost } from "./types.js";
+
+export interface ExternalInventoryDeclaration {
+  readonly path: string;
+  readonly shape: "foundry" | "custom";
+}
+
+export interface InventoryDriftReport {
+  readonly status: "no-external-source" | "reconciled" | "indeterminate";
+  readonly externalOnly: readonly string[];
+  readonly launcherOnly: readonly string[];
+  readonly agreeing: readonly string[];
+  readonly note?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reads a foundry-shaped inventory document's repository ids. Malformed or missing is null, never []. */
+function readForeignIds(host: WorkspaceHost, path: string): readonly string[] | null {
+  const raw = host.readText(path);
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.repositories)) return null;
+  const ids: string[] = [];
+  for (const entry of parsed.repositories) {
+    if (isRecord(entry) && typeof entry.id === "string" && entry.id.trim() !== "") ids.push(entry.id);
+  }
+  return ids;
+}
+
+/**
+ * Compares the declared external inventory against the launcher-written
+ * inventory at `directory/launcherInventoryRelPath`. Read-only -- callers
+ * decide whether and how to write the reconciled set, as an explicit,
+ * approved apply step (same #1045 pattern as clone-on-approval).
+ */
+export function reportInventoryDrift(
+  host: WorkspaceHost,
+  directory: string,
+  declaration: ExternalInventoryDeclaration | undefined,
+  launcherInventoryRelPath: string,
+): InventoryDriftReport {
+  if (declaration === undefined) {
+    return { status: "no-external-source", externalOnly: [], launcherOnly: [], agreeing: [] };
+  }
+  if (declaration.shape === "custom") {
+    return {
+      status: "indeterminate",
+      externalOnly: [],
+      launcherOnly: [],
+      agreeing: [],
+      note: `externalInventory at ${declaration.path} declares shape "custom"; launcher has no mapping for a non-foundry inventory shape yet and will not guess one. Reconcile by hand or file the mapping gap.`,
+    };
+  }
+  const externalIds = readForeignIds(host, declaration.path);
+  if (externalIds === null) {
+    return {
+      status: "indeterminate",
+      externalOnly: [],
+      launcherOnly: [],
+      agreeing: [],
+      note: `externalInventory at ${declaration.path} could not be read as a populated schemaVersion:1 inventory document.`,
+    };
+  }
+  const launcherIds = readForeignIds(host, `${directory}/${launcherInventoryRelPath}`) ?? [];
+  const externalSet = new Set(externalIds);
+  const launcherSet = new Set(launcherIds);
+  const externalOnly = externalIds.filter((id) => !launcherSet.has(id));
+  const launcherOnly = launcherIds.filter((id) => !externalSet.has(id));
+  const agreeing = externalIds.filter((id) => launcherSet.has(id));
+  return { status: "reconciled", externalOnly, launcherOnly, agreeing };
+}

package/src/manifest.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { SkillManifestDocument, SkillManifestEntry, SkillsManifestSummary, WorkspaceHost } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** sha256 hex digest of a skill's final composed content (post contract injection). */
+export function sha256Hex(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+/** Tiny semver-ish compare, duplicated from core.ts to keep this module dependency-free within the package. */
+function compareVersions(a: string, b: string): -1 | 0 | 1 | null {
+  const parse = (version: string): readonly number[] | null => {
+    const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let index = 0; index < 3; index += 1) {
+    const l = left[index] ?? 0;
+    const r = right[index] ?? 0;
+    if (l < r) return -1;
+    if (l > r) return 1;
+  }
+  return 0;
+}
+
+/** Parses `clossys/.state/skills.json`. An unreadable or malformed document is treated as absent. */
+export function parseSkillManifest(raw: string | null): SkillManifestDocument | undefined {
+  if (raw === null) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1 || !Array.isArray(parsed.skills)) return undefined;
+  const skills: SkillManifestEntry[] = [];
+  for (const entry of parsed.skills) {
+    if (!isRecord(entry)) continue;
+    const { name, source, sha256 } = entry;
+    if (typeof name !== "string" || name.trim() === "") continue;
+    if (source !== "installed" && source !== "catalogue") continue;
+    if (typeof sha256 !== "string" || sha256.trim() === "") continue;
+    skills.push({
+      name,
+      source,
+      sha256,
+      ...(typeof entry.version === "string" && entry.version.trim() !== "" ? { version: entry.version } : {}),
+    });
+  }
+  return {
+    schemaVersion: 1,
+    generatedAt: typeof parsed.generatedAt === "string" ? parsed.generatedAt : "",
+    skills,
+  };
+}
+
+export function serializeSkillManifest(document: SkillManifestDocument): string {
+  return `${JSON.stringify(document, null, 2)}\n`;
+}
+
+/**
+ * Freshness summary for the health report: "N skills out of date, M
+ * retired". `stale` counts catalogue-sourced entries whose recorded version
+ * is older than `liveLauncherVersion` (a client running an old launcher
+ * carries a catalogue only as fresh as that release, #1033) — unknown or
+ * unparseable versions are never counted stale. `retiredThisRun` is supplied
+ * by the composition step that just ran; a read-only inspection (no
+ * composition) reports 0 retired, which is correct — retirement is a
+ * this-run event, not a property of the manifest at rest.
+ */
+export function summarizeSkillsManifest(
+  manifest: SkillManifestDocument | undefined,
+  liveLauncherVersion: string | undefined,
+  retiredThisRun: readonly string[],
+): SkillsManifestSummary {
+  if (manifest === undefined) {
+    return { status: "missing", total: 0, stale: 0, retired: retiredThisRun.length };
+  }
+  const stale = manifest.skills.filter((entry) => {
+    if (entry.source !== "catalogue" || liveLauncherVersion === undefined || entry.version === undefined) return false;
+    return compareVersions(entry.version, liveLauncherVersion) === -1;
+  }).length;
+  return { status: "present", total: manifest.skills.length, stale, retired: retiredThisRun.length };
+}
+
+/** Reads `installed` version from `<composeTargetDirectory>/node_modules/@clossys/<pkg>/package.json`. */
+export function readInstalledVersion(host: WorkspaceHost, composeTargetDirectory: string, packageDir: string): string | undefined {
+  const raw = host.readText(join(composeTargetDirectory, "node_modules", "@clossys", packageDir, "package.json"));
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isRecord(parsed) && typeof parsed.version === "string" && parsed.version.trim() !== "") return parsed.version;
+  } catch {
+    /* unreadable manifest; no version */
+  }
+  return undefined;
+}