@clossys/launcher 0.1.5 → 0.3.1

package/src/apply-plan-cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { isDirectInvocation } from "./cli.js";
+import { createNodeHost } from "./host.js";
+import { applyEngagementBrief, validateAdvisorPlan, validateEngagementBrief, type AdvisorPlan, type EngagementBrief } from "./apply-plan.js";
+
+export const APPLY_PLAN_USAGE = `Usage: launcher-apply-plan --plan <plan.json> --brief <brief.json> --repo <directory>
+
+Writes clossys/brief.json into <directory> from the given brief, once the
+given plan's most recent decision is "approved". Refuses, and writes
+nothing, otherwise.
+
+Deterministic mechanics only: this does not decide whether a plan should be
+approved (that is Advisor's job) and does not compute the brief's content
+(that is @clossys/advisor's EngagementBrief, #1193) -- it validates the
+exact shapes recorded on issue #1175 and writes the one file.
+
+Exit codes: 0 = applied, 1 = refused (not approved, or a shape does not
+validate), 2 = a given file could not be read as JSON.`;
+
+export class ApplyPlanInputError extends Error {}
+
+function parseArgs(argv: readonly string[]): { help: boolean; planPath?: string; briefPath?: string; repoDirectory?: string } {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
+  const flags = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 2) {
+    const name = argv[index];
+    const value = argv[index + 1];
+    if ((name !== "--plan" && name !== "--brief" && name !== "--repo") || value === undefined) {
+      throw new ApplyPlanInputError("usage: launcher-apply-plan --plan <path> --brief <path> --repo <directory>");
+    }
+    flags.set(name, value);
+  }
+  const planPath = flags.get("--plan");
+  const briefPath = flags.get("--brief");
+  const repoDirectory = flags.get("--repo");
+  if (planPath === undefined || briefPath === undefined || repoDirectory === undefined) {
+    throw new ApplyPlanInputError("--plan, --brief, and --repo are all required");
+  }
+  return { help: false, planPath, briefPath, repoDirectory };
+}
+
+function readJson(readText: (path: string) => string | null, path: string, label: string): unknown {
+  const raw = readText(path);
+  if (raw === null) throw new ApplyPlanInputError(`${label} could not be read: ${path}`);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new ApplyPlanInputError(`${label} is not valid JSON: ${path}`);
+  }
+}
+
+export function main(argv: readonly string[], host: ReturnType<typeof createNodeHost>): number {
+  const parsed = parseArgs(argv);
+  if (parsed.help) {
+    console.log(APPLY_PLAN_USAGE);
+    return 0;
+  }
+  let planRaw: unknown;
+  let briefRaw: unknown;
+  try {
+    planRaw = readJson(host.readText, parsed.planPath as string, "--plan");
+    briefRaw = readJson(host.readText, parsed.briefPath as string, "--brief");
+  } catch (cause) {
+    console.error(`launcher-apply-plan: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return 2;
+  }
+  const planValidation = validateAdvisorPlan(planRaw);
+  if (!planValidation.valid) {
+    console.error(`launcher-apply-plan: --plan does not validate: ${planValidation.reason}`);
+    return 1;
+  }
+  const briefValidation = validateEngagementBrief(briefRaw);
+  if (!briefValidation.valid) {
+    console.error(`launcher-apply-plan: --brief does not validate: ${briefValidation.reason}`);
+    return 1;
+  }
+  const result = applyEngagementBrief(host, parsed.repoDirectory as string, planRaw as AdvisorPlan, briefRaw as EngagementBrief, "clossys/brief.json");
+  if (result.state === "refused") {
+    console.error(`launcher-apply-plan: refused -- ${result.reason}`);
+    return 1;
+  }
+  console.log(`wrote ${result.path}`);
+  return 0;
+}
+
+function run(): void {
+  try {
+    process.exitCode = main(process.argv.slice(2), createNodeHost());
+  } catch (cause) {
+    console.error(`launcher-apply-plan: ${cause instanceof Error ? cause.message : String(cause)}`);
+    process.exitCode = 2;
+  }
+}
+if (isDirectInvocation(import.meta.url, process.argv[1])) run();

package/src/apply-plan.ts

@@ -0,0 +1,172 @@
+// Apply an approved plan (#1178): writes clossys/brief.json into a staffed
+// repository from the exact EngagementBrief shape and plan.json contract
+// recorded on issue #1175 ("Plan file contract", posted 2026-09-22).
+//
+// SCOPE OF THIS MODULE (see the wave-2 PR body for the full explanation):
+// this lands the mechanical, auditable core the landed contract fully
+// specifies -- reading clossys/advisor/plan.json, confirming it is
+// approved, validating an EngagementBrief, and writing clossys/brief.json
+// byte-identically. Multi-repository orchestration (branch creation, exact
+// package installs, Starter's caller workflow, opening one pull request
+// per repository) is deferred: the landed contract does not yet specify
+// how a plan's approved roles map to inventory repository ids or to
+// install/remove/relocate work items, and building that mapping now would
+// mean inventing an interface Advisor's still-open PR (#1193) might define
+// differently.
+//
+// clossys/brief.json's shape is NOT re-derived here -- @clossys/advisor's
+// EngagementBrief export (landing in #1193) is the one owner of that
+// computation. This module receives an already-computed brief (as a file
+// path today; a direct call once #1193 lands and a caller can import the
+// package) and only validates its shape and writes it, exactly the split
+// #1187's governing principle draws between package-owned definition and
+// judgment versus Launcher's deterministic mechanics.
+
+import type { WorkspaceHost } from "./types.js";
+
+export interface EngagementBriefRole {
+  readonly role: string;
+  readonly why: string;
+  readonly goal: { readonly metric: string; readonly direction: "increase" | "decrease" };
+  readonly inputsFrom: readonly string[];
+  readonly outputsTo: readonly string[];
+}
+
+export interface EngagementBrief {
+  readonly schemaVersion: 1;
+  readonly problem: string;
+  readonly roles: readonly EngagementBriefRole[];
+  readonly sequence: readonly string[];
+  readonly deliverables: readonly string[];
+}
+
+export type BlockerKind = "missing-input" | "missing-authority" | "failing-evidence" | "unavailable-environment" | "contradiction";
+
+export interface PlanBlocker {
+  readonly kind: BlockerKind;
+  readonly description: string;
+  readonly owner: string;
+  readonly dueDate?: string;
+}
+
+export interface PlanDecision {
+  readonly at: string;
+  readonly recommended: string;
+  readonly chosen: string;
+  readonly by: string;
+}
+
+export interface AdvisorPlan {
+  readonly schemaVersion: 1;
+  readonly asOf: string;
+  readonly mandate: { readonly problem: string; readonly primaryProblemId: string; readonly roles: readonly string[] };
+  readonly whereWeAre: readonly string[];
+  readonly recommendedNext: { readonly action: string; readonly owner: string; readonly due: string } | null;
+  readonly decisions: readonly PlanDecision[];
+  readonly blockers: readonly PlanBlocker[];
+}
+
+export type ValidationResult = { readonly valid: true } | { readonly valid: false; readonly reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+/** Validates an EngagementBrief's shape exactly against the #1175 contract. Never mutates, never re-derives content. */
+export function validateEngagementBrief(value: unknown): ValidationResult {
+  if (!isRecord(value)) return { valid: false, reason: "brief must be an object" };
+  if (value.schemaVersion !== 1) return { valid: false, reason: "brief.schemaVersion must be 1" };
+  if (!nonEmptyString(value.problem)) return { valid: false, reason: "brief.problem must be a non-empty string" };
+  if (!Array.isArray(value.roles) || value.roles.length === 0) return { valid: false, reason: "brief.roles must be a non-empty array" };
+  for (const [index, role] of value.roles.entries()) {
+    if (!isRecord(role)) return { valid: false, reason: `brief.roles[${index}] must be an object` };
+    if (!nonEmptyString(role.role)) return { valid: false, reason: `brief.roles[${index}].role must be a non-empty string` };
+    if (!nonEmptyString(role.why)) return { valid: false, reason: `brief.roles[${index}].why must be a non-empty string` };
+    if (!isRecord(role.goal) || !nonEmptyString(role.goal.metric) || (role.goal.direction !== "increase" && role.goal.direction !== "decrease")) {
+      return { valid: false, reason: `brief.roles[${index}].goal must have a metric and a direction of increase or decrease` };
+    }
+    if (!stringArray(role.inputsFrom)) return { valid: false, reason: `brief.roles[${index}].inputsFrom must be a string array` };
+    if (!stringArray(role.outputsTo)) return { valid: false, reason: `brief.roles[${index}].outputsTo must be a string array` };
+  }
+  if (!stringArray(value.sequence) || value.sequence.length === 0) return { valid: false, reason: "brief.sequence must be a non-empty string array" };
+  if (!stringArray(value.deliverables)) return { valid: false, reason: "brief.deliverables must be a string array" };
+  return { valid: true };
+}
+
+const BLOCKER_KINDS = new Set<BlockerKind>(["missing-input", "missing-authority", "failing-evidence", "unavailable-environment", "contradiction"]);
+
+/** Validates an AdvisorPlan's shape exactly against the #1175 contract. */
+export function validateAdvisorPlan(value: unknown): ValidationResult {
+  if (!isRecord(value)) return { valid: false, reason: "plan must be an object" };
+  if (value.schemaVersion !== 1) return { valid: false, reason: "plan.schemaVersion must be 1" };
+  if (!nonEmptyString(value.asOf)) return { valid: false, reason: "plan.asOf must be a non-empty string" };
+  if (!isRecord(value.mandate) || !nonEmptyString(value.mandate.problem) || !nonEmptyString(value.mandate.primaryProblemId) || !stringArray(value.mandate.roles)) {
+    return { valid: false, reason: "plan.mandate must have problem, primaryProblemId, and a roles string array" };
+  }
+  if (!stringArray(value.whereWeAre)) return { valid: false, reason: "plan.whereWeAre must be a string array" };
+  if (value.recommendedNext !== null) {
+    if (!isRecord(value.recommendedNext) || !nonEmptyString(value.recommendedNext.action) || !nonEmptyString(value.recommendedNext.owner) || !nonEmptyString(value.recommendedNext.due)) {
+      return { valid: false, reason: "plan.recommendedNext must be null or have action, owner, and due" };
+    }
+  }
+  if (!Array.isArray(value.decisions)) return { valid: false, reason: "plan.decisions must be an array" };
+  for (const [index, decision] of value.decisions.entries()) {
+    if (!isRecord(decision) || !nonEmptyString(decision.at) || !nonEmptyString(decision.recommended) || !nonEmptyString(decision.chosen) || !nonEmptyString(decision.by)) {
+      return { valid: false, reason: `plan.decisions[${index}] must have at, recommended, chosen, and by` };
+    }
+  }
+  if (!Array.isArray(value.blockers)) return { valid: false, reason: "plan.blockers must be an array" };
+  for (const [index, blocker] of value.blockers.entries()) {
+    if (!isRecord(blocker) || !BLOCKER_KINDS.has(blocker.kind as BlockerKind) || !nonEmptyString(blocker.description) || !nonEmptyString(blocker.owner)) {
+      return { valid: false, reason: `plan.blockers[${index}] must have a valid kind, description, and owner` };
+    }
+  }
+  return { valid: true };
+}
+
+/**
+ * The plan is approved when its most recent decision (by `at`) records
+ * chosen === "approved". No decisions, or a most-recent decision that
+ * isn't "approved", is not approved -- this never assumes approval from
+ * absence.
+ */
+export function isPlanApproved(plan: AdvisorPlan): boolean {
+  if (plan.decisions.length === 0) return false;
+  const mostRecent = [...plan.decisions].sort((left, right) => Date.parse(left.at) - Date.parse(right.at)).at(-1);
+  return mostRecent?.chosen === "approved";
+}
+
+export type ApplyBriefResult =
+  | { readonly state: "applied"; readonly path: string }
+  | { readonly state: "refused"; readonly reason: string };
+
+/**
+ * Writes clossys/brief.json into `repositoryDirectory`, byte-identically
+ * from the validated brief -- never re-authors its prose. Refuses (does
+ * not write) unless both the plan is approved and the brief validates.
+ */
+export function applyEngagementBrief(
+  host: WorkspaceHost,
+  repositoryDirectory: string,
+  plan: AdvisorPlan,
+  brief: EngagementBrief,
+  briefRelPath: string,
+): ApplyBriefResult {
+  if (!isPlanApproved(plan)) {
+    return { state: "refused", reason: "the plan's most recent decision is not \"approved\"" };
+  }
+  const validation = validateEngagementBrief(brief);
+  if (!validation.valid) {
+    return { state: "refused", reason: `brief does not validate: ${validation.reason}` };
+  }
+  const path = `${repositoryDirectory}/${briefRelPath}`;
+  host.mkdirp(path.slice(0, path.lastIndexOf("/")));
+  host.writeText(path, `${JSON.stringify(brief, null, 2)}\n`);
+  return { state: "applied", path };
+}

package/src/check-cli.ts

@@ -120,6 +120,9 @@ export function planningHost(): WorkspaceHost {
     symlink: () => {
       throw new Error("launcher-check does not write");
     },
+    remove: () => {
+      throw new Error("launcher-check does not write");
+    },
     readDir: () => [],
     run: () => unused(),
     prompt: () => null,

package/src/cli.ts

@@ -2,11 +2,19 @@
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { applyWorkspacePlan, observeWorkspace, planWorkspace, launcherPackageRootFromModule, skeletonRootFromModule } from "./core.js";
+import {
+  applyWorkspacePlan,
+  cloneMissingInventoryRepositories,
+  observeWorkspace,
+  planWorkspace,
+  launcherPackageRootFromModule,
+  readLiveLauncherVersion,
+  skeletonRootFromModule,
+} from "./core.js";
 import { createNodeHost } from "./host.js";
 import type { WorkspaceHost } from "./types.js";
 
-export const USAGE = `Usage: launcher [--inventory <path>]
+export const USAGE = `Usage: launcher [--inventory <path>] [--clone-missing]
 
 Create, resume, or appoint a GitHub repository as the account workspace hub.
 
@@ -16,9 +24,15 @@ hub to appoint it — it does not have to be a new exclusive repo, and it keeps
 its current name and files.
 
 Appointing requires a populated generated hub inventory (packed template
-skeleton/.clossys/inventory.json; the generated path does not ship), or
+skeleton/clossys/.state/inventory.json; the generated path does not ship), or
 --inventory <path> pointing at one. Resume refreshes composed skills and
-stale hub guidance. Create may write an empty inventory.
+stale hub guidance, and migrates a legacy .clossys/ hub state to
+clossys/.state/ automatically. Create may write an empty inventory.
+
+By default launcher never \`gh repo clone\`s a missing inventory entry --
+that is not how you talk to the team. --clone-missing is the one explicit,
+approved exception (#1179): on resume only, it clones every inventoried
+repository not yet sitting beside the hub, and only those.
 
 GitHub-only. Owner is inferred from \`gh\` and git remotes. Public npm reads
 need no token.
@@ -31,11 +45,20 @@ function exitCodeFor(state: "satisfied" | "violated" | "indeterminate"): number
   return state === "satisfied" ? 0 : state === "violated" ? 1 : 2;
 }
 
-export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string } {
-  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true };
-  if (argv.length === 0) return { help: false };
-  if (argv.length === 2 && argv[0] === "--inventory" && argv[1]) return { help: false, inventoryPath: argv[1] };
-  throw new LauncherInputError("launcher takes no arguments except optional --inventory <path>; run it from the directory to create or appoint");
+export function parseLauncherArgs(argv: readonly string[]): { help: boolean; inventoryPath?: string; cloneMissing: boolean } {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) return { help: true, cloneMissing: false };
+  const rest = [...argv];
+  let cloneMissing = false;
+  const cloneIndex = rest.indexOf("--clone-missing");
+  if (cloneIndex !== -1) {
+    cloneMissing = true;
+    rest.splice(cloneIndex, 1);
+  }
+  if (rest.length === 0) return { help: false, cloneMissing };
+  if (rest.length === 2 && rest[0] === "--inventory" && rest[1]) return { help: false, inventoryPath: rest[1], cloneMissing };
+  throw new LauncherInputError(
+    "launcher takes no arguments except optional --inventory <path> and/or --clone-missing; run it from the directory to create or appoint",
+  );
 }
 
 /** Testable CLI dispatcher. Unknown arguments throw; the executable maps them to exit 2. */
@@ -62,16 +85,28 @@ export function main(argv: readonly string[], host: WorkspaceHost, skeletonRoot:
   }
   if (parsed.inventoryPath !== undefined && decision.action !== "adopt") {
     if (decision.action === "resume") {
-      console.error("launcher: this hub is already appointed; edit .clossys/inventory.json to change its inventory");
+      console.error("launcher: this hub is already appointed; edit clossys/.state/inventory.json to change its inventory");
     } else {
       console.error("launcher: --inventory is only valid when appointing a GitHub repository");
     }
     return 1;
   }
+  if (parsed.cloneMissing && decision.action !== "resume") {
+    console.error("launcher: --clone-missing is only valid on an already-appointed hub (resume)");
+    return 1;
+  }
   const result = applyWorkspacePlan(host, decision, skeletonRoot, {
     launcherPackageRoot: launcherPackageRootFromModule(import.meta.url),
+    liveLauncherVersion: readLiveLauncherVersion(host),
   });
   console.log(result.message);
+  if (parsed.cloneMissing && decision.action === "resume") {
+    const outcomes = cloneMissingInventoryRepositories(host, decision.directory, decision.owner);
+    for (const outcome of outcomes) {
+      if (outcome.result === "skipped-other-reason") continue;
+      console.log(`clone-missing (${outcome.inventoryId}): ${outcome.result} -- ${outcome.note}`);
+    }
+  }
   return 0;
 }
 

package/src/contract.ts

@@ -0,0 +1,81 @@
+/**
+ * The single conversation contract every composed skill carries (#1182).
+ * Source of truth: the conversation-contract document kept in this
+ * monorepo's shared contracts directory (not part of this package's own
+ * published files). This package's own build step packs it into `contracts/`
+ * so the published tarball is self-contained.
+ */
+
+const CONTRACT_HEADING = "## How we work together";
+const LEGACY_HEADING = "## One question at a time";
+const INSTALLED_HEADING = "## When this package is installed";
+
+function lineIndex(lines: readonly string[], heading: string, from = 0): number {
+  for (let index = from; index < lines.length; index += 1) {
+    if ((lines[index] ?? "").trim() === heading) return index;
+  }
+  return -1;
+}
+
+/**
+ * Extracts the injectable block from the raw conversation-contract.md text:
+ * everything from its `## How we work together` heading to end of file,
+ * trimmed. Content above that heading (a title, a provenance note) is
+ * documentation for a human reader of the contract file itself and is never
+ * injected.
+ */
+export function extractContractBlock(rawDocText: string): string {
+  const lines = rawDocText.split("\n");
+  const index = lineIndex(lines, CONTRACT_HEADING);
+  if (index === -1) {
+    throw new Error("conversation contract document is missing its `## How we work together` heading");
+  }
+  return lines.slice(index).join("\n").trim();
+}
+
+/**
+ * Replaces a skill's own `## How we work together` and `## One question at a
+ * time` sections (if present) with the shared conversation contract, at the
+ * same position. When neither heading is present, inserts the contract
+ * before `## When this package is installed` if that heading exists, else
+ * appends it at the end of the file. A blank line is preserved (or added)
+ * on both sides of the inserted block; existing content is otherwise left
+ * untouched. Idempotent: composing an already-composed skill a second time
+ * (the contract's own heading is `## How we work together`, so a repeat run
+ * finds and replaces exactly the block it wrote) leaves it unchanged.
+ */
+export function injectContract(skillBody: string, contractBlock: string): string {
+  const contract = contractBlock.trim();
+  const lines = skillBody.split("\n");
+  const howIdx = lineIndex(lines, CONTRACT_HEADING);
+  const oneIdx = lineIndex(lines, LEGACY_HEADING);
+
+  let start: number;
+  let end: number;
+  if (howIdx !== -1 || oneIdx !== -1) {
+    start = howIdx === -1 ? oneIdx : oneIdx === -1 ? howIdx : Math.min(howIdx, oneIdx);
+    end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+      const trimmed = (lines[index] ?? "").trim();
+      if (trimmed.startsWith("## ") && trimmed !== CONTRACT_HEADING && trimmed !== LEGACY_HEADING) {
+        end = index;
+        break;
+      }
+    }
+  } else {
+    const installedIdx = lineIndex(lines, INSTALLED_HEADING);
+    start = installedIdx === -1 ? lines.length : installedIdx;
+    end = start;
+  }
+
+  const before = lines.slice(0, start);
+  const after = lines.slice(end);
+  const needsLeadingBlank = before.length > 0 && (before[before.length - 1] ?? "").trim() !== "";
+  const needsTrailingBlank = after.length > 0 && (after[0] ?? "").trim() !== "";
+  const block = [
+    ...(needsLeadingBlank ? [""] : []),
+    ...contract.split("\n"),
+    ...(needsTrailingBlank ? [""] : []),
+  ];
+  return [...before, ...block, ...after].join("\n");
+}