libretto 0.6.18 → 0.6.19

package/dist/cli/cli.js

@@ -2,14 +2,14 @@ import { ensureLibrettoSetup } from "./core/context.js";
 import { createCLIApp } from "./router.js";
 import {
   readCurrentCliVersion,
-  warnIfInstalledSkillOutOfDate
+  warnIfLibrettoVersionsDiffer
 } from "./core/skill-version.js";
 import { loadEnv } from "../shared/env/load-env.js";
 function renderVersion() {
   return readCurrentCliVersion();
 }
 function printSetupAudit() {
-  warnIfInstalledSkillOutOfDate();
+  warnIfLibrettoVersionsDiffer();
 }
 function isPackageManagerExec(env = process.env) {
   return env.npm_command === "exec";

package/dist/cli/commands/browser.js

@@ -17,7 +17,7 @@ import {
   setSessionMode,
   validateSessionName
 } from "../core/session.js";
-import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
+import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
 import { SimpleCLI } from "affordance";
 import {
   sessionOption,
@@ -88,7 +88,7 @@ const openInput = SimpleCLI.input({
 const openCommand = SimpleCLI.command({
   description: "Launch browser and open URL"
 }).input(openInput).use(withAutoSession()).use(withExperiments()).handle(async ({ input, ctx }) => {
-  warnIfInstalledSkillOutOfDate();
+  warnIfLibrettoVersionsDiffer();
   assertSessionAvailableForStart(ctx.session, ctx.logger);
   const providerName = resolveProviderName(input.provider);
   if (providerName === "local") {
@@ -141,7 +141,7 @@ const connectInput = SimpleCLI.input({
 const connectCommand = SimpleCLI.command({
   description: "Connect to an existing Chrome DevTools Protocol (CDP) endpoint"
 }).input(connectInput).use(withAutoSession()).use(withExperiments()).handle(async ({ input, ctx }) => {
-  warnIfInstalledSkillOutOfDate();
+  warnIfLibrettoVersionsDiffer();
   await runConnectWithLogger(
     input.cdpUrl,
     ctx.session,

package/dist/cli/commands/execution.js

@@ -23,7 +23,7 @@ import {
   setSessionStatus,
   writeSessionState
 } from "../core/session.js";
-import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
+import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
 import { readLibrettoConfig } from "../core/config.js";
 import { renderSnapshotDiff } from "../../shared/snapshot/diff-snapshots.js";
 import {
@@ -682,7 +682,7 @@ function resolveRunParams(rawInlineParams, paramsFile) {
 const runCommand = SimpleCLI.command({
   description: "Run the default-exported Libretto workflow from a file"
 }).input(runInput).use(withAutoSession()).use(withExperiments()).handle(async ({ input, ctx }) => {
-  warnIfInstalledSkillOutOfDate();
+  warnIfLibrettoVersionsDiffer();
   await stopExistingFailedRunSession(ctx.session, ctx.logger);
   assertSessionAvailableForStart(ctx.session, ctx.logger);
   const params = resolveRunParams(input.params, input.paramsFile);

package/dist/cli/core/skill-version.js

@@ -7,6 +7,15 @@ const INSTALLED_SKILL_PATHS = [
   [".claude", "skills", "libretto", "SKILL.md"]
 ];
 let cachedCliVersion = null;
+function readPackageVersion(packageJsonPath) {
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+  const manifest = JSON.parse(
+    readFileSync(packageJsonPath, "utf8")
+  );
+  return manifest.version?.trim() || null;
+}
 function readCurrentCliVersion() {
   if (cachedCliVersion) {
     return cachedCliVersion;
@@ -14,17 +23,20 @@ function readCurrentCliVersion() {
   const packageJsonPath = fileURLToPath(
     new URL("../../../package.json", import.meta.url)
   );
-  const manifest = JSON.parse(
-    readFileSync(packageJsonPath, "utf8")
-  );
-  if (!manifest.version) {
+  const version = readPackageVersion(packageJsonPath);
+  if (!version) {
     throw new Error(
       `Unable to determine current libretto version from ${packageJsonPath}.`
     );
   }
-  cachedCliVersion = manifest.version;
+  cachedCliVersion = version;
   return cachedCliVersion;
 }
+function readLocalPackageVersion() {
+  return readPackageVersion(
+    join(REPO_ROOT, "node_modules", "libretto", "package.json")
+  );
+}
 function readInstalledSkillVersion(skillPath) {
   if (!existsSync(skillPath)) {
     return null;
@@ -45,30 +57,139 @@ function readInstalledSkillVersion(skillPath) {
   );
   return versionMatch?.[1]?.trim() ?? null;
 }
-function findInstalledSkillVersionMismatch() {
-  const cliVersion = readCurrentCliVersion();
+function readInstalledSkillVersions() {
+  const versions = /* @__PURE__ */ new Set();
   for (const relativePathParts of INSTALLED_SKILL_PATHS) {
     const skillPath = join(REPO_ROOT, ...relativePathParts);
     const installedVersion = readInstalledSkillVersion(skillPath);
-    if (installedVersion && installedVersion !== cliVersion) {
-      return { installedVersion, cliVersion };
+    if (installedVersion) {
+      versions.add(installedVersion);
+    }
+  }
+  return [...versions];
+}
+function parseVersion(version) {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null
+  };
+}
+function compareVersions(left, right) {
+  const parsedLeft = parseVersion(left);
+  const parsedRight = parseVersion(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right);
+  }
+  for (const key of ["major", "minor", "patch"]) {
+    const diff = parsedLeft[key] - parsedRight[key];
+    if (diff !== 0) {
+      return diff;
     }
   }
-  return null;
+  if (parsedLeft.prerelease === parsedRight.prerelease) {
+    return 0;
+  }
+  if (parsedLeft.prerelease === null) {
+    return 1;
+  }
+  if (parsedRight.prerelease === null) {
+    return -1;
+  }
+  return parsedLeft.prerelease.localeCompare(parsedRight.prerelease);
+}
+function selectTargetVersion(versions) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const version of versions) {
+    counts.set(version, (counts.get(version) ?? 0) + 1);
+  }
+  const byCountThenVersion = [...counts.entries()].sort(
+    ([leftVersion, leftCount], [rightVersion, rightCount]) => rightCount - leftCount || compareVersions(rightVersion, leftVersion)
+  );
+  return byCountThenVersion[0]?.[0] ?? versions[0] ?? "latest";
+}
+function formatVersion(version, targetVersion) {
+  return version === targetVersion ? version : `${version}  (out of date)`;
+}
+function formatSkillVersions(versions, targetVersion) {
+  if (versions.length === 0) {
+    return "not installed";
+  }
+  return versions.map((version) => formatVersion(version, targetVersion)).join(", ");
+}
+function formatUpdateInstructions(components) {
+  const instructions = [];
+  if (components.cliVersion !== components.targetVersion) {
+    instructions.push(
+      `  global CLI:    curl -fsSL https://libretto.sh/install.sh | LIBRETTO_VERSION=${components.targetVersion} bash`
+    );
+  }
+  if (components.localPackageVersion && components.localPackageVersion !== components.targetVersion) {
+    instructions.push(
+      `  local package: npm install libretto@${components.targetVersion}`
+    );
+  }
+  if (components.skillVersions.length > 0 && components.skillVersions.some(
+    (skillVersion) => skillVersion !== components.targetVersion
+  )) {
+    instructions.push("  agent skill:   libretto setup");
+  }
+  return instructions;
+}
+function formatVersionWarning(components) {
+  const targetVersion = selectTargetVersion([
+    components.cliVersion,
+    ...components.localPackageVersion ? [components.localPackageVersion] : [],
+    ...components.skillVersions
+  ]);
+  const skillLabel = components.skillVersions.length > 1 ? "agent skills" : "agent skill";
+  const updateInstructions = formatUpdateInstructions({
+    ...components,
+    targetVersion
+  });
+  return [
+    "WARNING: Libretto version mismatch detected.",
+    "",
+    `  global CLI:    ${formatVersion(components.cliVersion, targetVersion)}`,
+    `  local package: ${components.localPackageVersion ? formatVersion(components.localPackageVersion, targetVersion) : "not installed"}`,
+    `  ${skillLabel}:   ${formatSkillVersions(
+      components.skillVersions,
+      targetVersion
+    )}`,
+    "",
+    "How to update:",
+    ...updateInstructions
+  ].join("\n");
 }
-function warnIfInstalledSkillOutOfDate() {
+function warnIfLibrettoVersionsDiffer() {
   try {
-    const mismatch = findInstalledSkillVersionMismatch();
-    if (!mismatch) {
+    const cliVersion = readCurrentCliVersion();
+    const localPackageVersion = readLocalPackageVersion();
+    const skillVersions = readInstalledSkillVersions();
+    const observedVersions = /* @__PURE__ */ new Set([
+      cliVersion,
+      ...localPackageVersion ? [localPackageVersion] : [],
+      ...skillVersions
+    ]);
+    if (observedVersions.size <= 1) {
       return;
     }
     console.error(
-      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`libretto setup\` to update your skills to the correct version.`
+      formatVersionWarning({
+        cliVersion,
+        localPackageVersion,
+        skillVersions
+      })
     );
   } catch {
   }
 }
 export {
   readCurrentCliVersion,
-  warnIfInstalledSkillOutOfDate
+  warnIfLibrettoVersionsDiffer
 };

package/docs/releasing.md

@@ -28,17 +28,19 @@ GitHub Actions needs these repository secrets:
 
 The release workflow uses a GitHub Actions environment named `release`. Create that environment in the repository settings (no required reviewers — access is controlled by branch protection on `main` instead).
 
-On npm, configure `libretto` to trust this repository and workflow for publishing. The trusted publisher fields should match:
+On npm, configure each published package to trust this repository and workflow for publishing:
 
 - Organization or user: `saffron-health`
 - Repository: `libretto`
 - Workflow filename: `release.yml`
 - Environment name: `release`
 
-If you prefer the CLI, the setup command is:
+If you prefer the CLI, run one setup command per package with npm 11.10.0 or newer:
 
 ```bash
-npm trust github libretto --repo saffron-health/libretto --file release.yml --env release
+npx --yes npm@11.13.0 trust github libretto --repo saffron-health/libretto --file release.yml --env release --yes
+npx --yes npm@11.13.0 trust github affordance --repo saffron-health/libretto --file release.yml --env release --yes
+npx --yes npm@11.13.0 trust github create-libretto --repo saffron-health/libretto --file release.yml --env release --yes
 ```
 
 Trusted publishing only works on supported cloud-hosted runners. This workflow uses `ubuntu-latest`, which satisfies that requirement. npm also requires a recent toolchain for trusted publishing, so the publish job runs on Node 24.
@@ -80,7 +82,7 @@ The workflow:
 1. Reads the version from `packages/libretto/package.json`.
 2. Checks whether that version already exists on npm and in GitHub Releases.
 3. Runs install, type-check, and tests for the `libretto` package in a verification job.
-4. Publishes `libretto@X.Y.Z` to npm from `packages/libretto` with trusted publishing if it is not already published.
+4. Publishes `affordance` first, then `libretto@X.Y.Z`, then `create-libretto@X.Y.Z` with trusted publishing.
 5. Creates GitHub release `vX.Y.Z` with generated release notes if it does not already exist.
 
 This makes the workflow safe to re-run after partial failures. For example, if npm publish succeeds but GitHub release creation fails, a re-run will skip npm and only create the missing release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "homepage": "https://libretto.sh",

package/skills/libretto/SKILL.md

@@ -4,7 +4,7 @@ description: "Browser automation CLI for building, maintaining, and running brow
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.18"
+  version: "0.6.19"
 ---
 
 ## How Libretto Works

package/skills/libretto-readonly/SKILL.md

@@ -4,7 +4,7 @@ description: "Read-only Libretto workflow for diagnosing live browser state with
 license: MIT
 metadata:
   author: saffron-health
-  version: "0.6.18"
+  version: "0.6.19"
 ---
 
 ## How Libretto Read-Only Works

package/src/cli/cli.ts

@@ -2,7 +2,7 @@ import { ensureLibrettoSetup } from "./core/context.js";
 import { createCLIApp } from "./router.js";
 import {
   readCurrentCliVersion,
-  warnIfInstalledSkillOutOfDate,
+  warnIfLibrettoVersionsDiffer,
 } from "./core/skill-version.js";
 import { loadEnv } from "../shared/env/load-env.js";
 
@@ -11,7 +11,7 @@ function renderVersion(): string {
 }
 
 function printSetupAudit(): void {
-  warnIfInstalledSkillOutOfDate();
+  warnIfLibrettoVersionsDiffer();
 }
 
 function isPackageManagerExec(env: NodeJS.ProcessEnv = process.env): boolean {

package/src/cli/commands/browser.ts

@@ -18,7 +18,7 @@ import {
   setSessionMode,
   validateSessionName,
 } from "../core/session.js";
-import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
+import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
 import { SimpleCLI } from "affordance";
 import {
   sessionOption,
@@ -107,7 +107,7 @@ export const openCommand = SimpleCLI.command({
   .use(withAutoSession())
   .use(withExperiments())
   .handle(async ({ input, ctx }) => {
-    warnIfInstalledSkillOutOfDate();
+    warnIfLibrettoVersionsDiffer();
     assertSessionAvailableForStart(ctx.session, ctx.logger);
     const providerName = resolveProviderName(input.provider);
     if (providerName === "local") {
@@ -168,7 +168,7 @@ export const connectCommand = SimpleCLI.command({
   .use(withAutoSession())
   .use(withExperiments())
   .handle(async ({ input, ctx }) => {
-    warnIfInstalledSkillOutOfDate();
+    warnIfLibrettoVersionsDiffer();
     await runConnectWithLogger(
       input.cdpUrl!,
       ctx.session,

package/src/cli/commands/execution.ts

@@ -25,7 +25,7 @@ import {
   writeSessionState,
   type SessionState,
 } from "../core/session.js";
-import { warnIfInstalledSkillOutOfDate } from "../core/skill-version.js";
+import { warnIfLibrettoVersionsDiffer } from "../core/skill-version.js";
 import { readLibrettoConfig } from "../core/config.js";
 import { renderSnapshotDiff } from "../../shared/snapshot/diff-snapshots.js";
 import {
@@ -860,7 +860,7 @@ export const runCommand = SimpleCLI.command({
   .use(withAutoSession())
   .use(withExperiments())
   .handle(async ({ input, ctx }) => {
-    warnIfInstalledSkillOutOfDate();
+    warnIfLibrettoVersionsDiffer();
     await stopExistingFailedRunSession(ctx.session, ctx.logger);
     assertSessionAvailableForStart(ctx.session, ctx.logger);
 

package/src/cli/core/skill-version.ts

@@ -14,6 +14,17 @@ const INSTALLED_SKILL_PATHS = [
 
 let cachedCliVersion: string | null = null;
 
+function readPackageVersion(packageJsonPath: string): string | null {
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+
+  const manifest = JSON.parse(
+    readFileSync(packageJsonPath, "utf8"),
+  ) as PackageManifest;
+  return manifest.version?.trim() || null;
+}
+
 export function readCurrentCliVersion(): string {
   if (cachedCliVersion) {
     return cachedCliVersion;
@@ -22,20 +33,24 @@ export function readCurrentCliVersion(): string {
   const packageJsonPath = fileURLToPath(
     new URL("../../../package.json", import.meta.url),
   );
-  const manifest = JSON.parse(
-    readFileSync(packageJsonPath, "utf8"),
-  ) as PackageManifest;
+  const version = readPackageVersion(packageJsonPath);
 
-  if (!manifest.version) {
+  if (!version) {
     throw new Error(
       `Unable to determine current libretto version from ${packageJsonPath}.`,
     );
   }
 
-  cachedCliVersion = manifest.version;
+  cachedCliVersion = version;
   return cachedCliVersion;
 }
 
+function readLocalPackageVersion(): string | null {
+  return readPackageVersion(
+    join(REPO_ROOT, "node_modules", "libretto", "package.json"),
+  );
+}
+
 function readInstalledSkillVersion(skillPath: string): string | null {
   if (!existsSync(skillPath)) {
     return null;
@@ -60,32 +75,188 @@ function readInstalledSkillVersion(skillPath: string): string | null {
   return versionMatch?.[1]?.trim() ?? null;
 }
 
-function findInstalledSkillVersionMismatch(): {
-  installedVersion: string;
-  cliVersion: string;
-} | null {
-  const cliVersion = readCurrentCliVersion();
+function readInstalledSkillVersions(): string[] {
+  const versions = new Set<string>();
 
   for (const relativePathParts of INSTALLED_SKILL_PATHS) {
     const skillPath = join(REPO_ROOT, ...relativePathParts);
     const installedVersion = readInstalledSkillVersion(skillPath);
-    if (installedVersion && installedVersion !== cliVersion) {
-      return { installedVersion, cliVersion };
+    if (installedVersion) {
+      versions.add(installedVersion);
     }
   }
 
-  return null;
+  return [...versions];
 }
 
-export function warnIfInstalledSkillOutOfDate(): void {
+function parseVersion(version: string): {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string | null;
+} | null {
+  const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null,
+  };
+}
+
+function compareVersions(left: string, right: string): number {
+  const parsedLeft = parseVersion(left);
+  const parsedRight = parseVersion(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right);
+  }
+
+  for (const key of ["major", "minor", "patch"] as const) {
+    const diff = parsedLeft[key] - parsedRight[key];
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+
+  if (parsedLeft.prerelease === parsedRight.prerelease) {
+    return 0;
+  }
+  if (parsedLeft.prerelease === null) {
+    return 1;
+  }
+  if (parsedRight.prerelease === null) {
+    return -1;
+  }
+  return parsedLeft.prerelease.localeCompare(parsedRight.prerelease);
+}
+
+function selectTargetVersion(versions: string[]): string {
+  const counts = new Map<string, number>();
+  for (const version of versions) {
+    counts.set(version, (counts.get(version) ?? 0) + 1);
+  }
+
+  const byCountThenVersion = [...counts.entries()].sort(
+    ([leftVersion, leftCount], [rightVersion, rightCount]) =>
+      rightCount - leftCount || compareVersions(rightVersion, leftVersion),
+  );
+
+  return byCountThenVersion[0]?.[0] ?? versions[0] ?? "latest";
+}
+
+function formatVersion(version: string, targetVersion: string): string {
+  return version === targetVersion ? version : `${version}  (out of date)`;
+}
+
+function formatSkillVersions(
+  versions: string[],
+  targetVersion: string,
+): string {
+  if (versions.length === 0) {
+    return "not installed";
+  }
+
+  return versions
+    .map((version) => formatVersion(version, targetVersion))
+    .join(", ");
+}
+
+function formatUpdateInstructions(components: {
+  cliVersion: string;
+  localPackageVersion: string | null;
+  skillVersions: string[];
+  targetVersion: string;
+}): string[] {
+  const instructions: string[] = [];
+
+  if (components.cliVersion !== components.targetVersion) {
+    instructions.push(
+      `  global CLI:    curl -fsSL https://libretto.sh/install.sh | LIBRETTO_VERSION=${components.targetVersion} bash`,
+    );
+  }
+
+  if (
+    components.localPackageVersion &&
+    components.localPackageVersion !== components.targetVersion
+  ) {
+    instructions.push(
+      `  local package: npm install libretto@${components.targetVersion}`,
+    );
+  }
+
+  if (
+    components.skillVersions.length > 0 &&
+    components.skillVersions.some(
+      (skillVersion) => skillVersion !== components.targetVersion,
+    )
+  ) {
+    instructions.push("  agent skill:   libretto setup");
+  }
+
+  return instructions;
+}
+
+function formatVersionWarning(components: {
+  cliVersion: string;
+  localPackageVersion: string | null;
+  skillVersions: string[];
+}): string {
+  const targetVersion = selectTargetVersion([
+    components.cliVersion,
+    ...(components.localPackageVersion ? [components.localPackageVersion] : []),
+    ...components.skillVersions,
+  ]);
+  const skillLabel =
+    components.skillVersions.length > 1 ? "agent skills" : "agent skill";
+  const updateInstructions = formatUpdateInstructions({
+    ...components,
+    targetVersion,
+  });
+
+  return [
+    "WARNING: Libretto version mismatch detected.",
+    "",
+    `  global CLI:    ${formatVersion(components.cliVersion, targetVersion)}`,
+    `  local package: ${
+      components.localPackageVersion
+        ? formatVersion(components.localPackageVersion, targetVersion)
+        : "not installed"
+    }`,
+    `  ${skillLabel}:   ${formatSkillVersions(
+      components.skillVersions,
+      targetVersion,
+    )}`,
+    "",
+    "How to update:",
+    ...updateInstructions,
+  ].join("\n");
+}
+
+export function warnIfLibrettoVersionsDiffer(): void {
   try {
-    const mismatch = findInstalledSkillVersionMismatch();
-    if (!mismatch) {
+    const cliVersion = readCurrentCliVersion();
+    const localPackageVersion = readLocalPackageVersion();
+    const skillVersions = readInstalledSkillVersions();
+    const observedVersions = new Set([
+      cliVersion,
+      ...(localPackageVersion ? [localPackageVersion] : []),
+      ...skillVersions,
+    ]);
+
+    if (observedVersions.size <= 1) {
       return;
     }
 
     console.error(
-      `Warning: Your agent skill (${mismatch.installedVersion}) is out of date with your Libretto CLI (${mismatch.cliVersion}). Please run \`libretto setup\` to update your skills to the correct version.`,
+      formatVersionWarning({
+        cliVersion,
+        localPackageVersion,
+        skillVersions,
+      }),
     );
   } catch {
     // Never block command execution on a best-effort skill version check.