gemi 0.59.0 → 0.60.0

package/dist/bin/gemi.js

@@ -35925,8 +35925,8 @@ var require_commander = __commonJS((exports) => {
 });
 
 // bin/gemi.ts
-import path4 from "path";
-import { existsSync as existsSync5 } from "fs";
+import path7 from "path";
+import { existsSync as existsSync8 } from "fs";
 
 // bin/createRollupInput.ts
 var {Glob } = globalThis.Bun;
@@ -39776,15 +39776,484 @@ class ApiManifestGenerator {
   }
 }
 
+// bin/version.ts
+import { existsSync as existsSync5, readFileSync as readFileSync2 } from "fs";
+import path4 from "path";
+var VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function parseVersion(version) {
+  const match = VERSION_RE.exec(version.trim());
+  if (!match)
+    return null;
+  const [, major, minor, patch, prerelease] = match;
+  return {
+    core: [Number(major), Number(minor), Number(patch)],
+    prerelease: prerelease ? prerelease.split(".") : []
+  };
+}
+var NUMERIC_RE = /^\d+$/;
+function comparePrereleaseIdentifiers(a, b) {
+  const aNumeric = NUMERIC_RE.test(a);
+  const bNumeric = NUMERIC_RE.test(b);
+  if (aNumeric && bNumeric)
+    return Number(a) - Number(b);
+  if (aNumeric)
+    return -1;
+  if (bNumeric)
+    return 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right)
+    return 0;
+  for (let i = 0;i < 3; i++) {
+    const diff = left.core[i] - right.core[i];
+    if (diff !== 0)
+      return diff;
+  }
+  if (left.prerelease.length === 0 && right.prerelease.length === 0)
+    return 0;
+  if (left.prerelease.length === 0)
+    return 1;
+  if (right.prerelease.length === 0)
+    return -1;
+  const shared = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let i = 0;i < shared; i++) {
+    const diff = comparePrereleaseIdentifiers(left.prerelease[i], right.prerelease[i]);
+    if (diff !== 0)
+      return diff;
+  }
+  return left.prerelease.length - right.prerelease.length;
+}
+function channelFor(version) {
+  const parsed = parseVersion(version);
+  const first = parsed?.prerelease[0];
+  return first && !NUMERIC_RE.test(first) ? first : "latest";
+}
+function findGemiPackageDir(rootDir) {
+  let dir = path4.resolve(rootDir);
+  while (true) {
+    const candidate = path4.join(dir, "node_modules", "gemi");
+    if (existsSync5(path4.join(candidate, "package.json")))
+      return candidate;
+    const parent = path4.dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function readInstalledVersion(rootDir) {
+  const packageDir = findGemiPackageDir(rootDir);
+  if (!packageDir)
+    return null;
+  try {
+    const manifest = JSON.parse(readFileSync2(path4.join(packageDir, "package.json"), "utf8"));
+    return typeof manifest?.version === "string" ? manifest.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// bin/registry.ts
+var DEFAULT_REGISTRY = "https://registry.npmjs.org";
+async function fetchPublishedVersion(tag, options = {}) {
+  const {
+    timeoutMs = 2000,
+    registry = process.env.GEMI_REGISTRY ?? DEFAULT_REGISTRY,
+    fetchImpl = fetch
+  } = options;
+  const controller = new AbortController;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(`${registry.replace(/\/+$/, "")}/gemi/${encodeURIComponent(tag)}`, {
+      signal: controller.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!response.ok)
+      return null;
+    const body = await response.json();
+    return typeof body?.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchNewestPublished(installed, options = {}) {
+  const channel = channelFor(installed);
+  if (channel === "latest")
+    return fetchPublishedVersion("latest", options);
+  const [onChannel, onLatest] = await Promise.all([
+    fetchPublishedVersion(channel, options),
+    fetchPublishedVersion("latest", options)
+  ]);
+  if (!onChannel)
+    return onLatest;
+  if (!onLatest)
+    return onChannel;
+  return compareVersions(onLatest, onChannel) > 0 ? onLatest : onChannel;
+}
+
+// bin/update-check.ts
+function shouldCheckForUpdate(env) {
+  if (env.GEMI_NO_UPDATE_CHECK)
+    return false;
+  if (env.CI)
+    return false;
+  return true;
+}
+function formatUpdateNotice(installed, published) {
+  if (compareVersions(published, installed) <= 0)
+    return null;
+  const from = parseVersion(installed);
+  const to = parseVersion(published);
+  const breaking = !!from && !!to && (from.core[0] !== to.core[0] || from.core[1] !== to.core[1]);
+  return [
+    `
+  Update available: gemi ${installed} \u2192 ${published}`,
+    `  Run \`gemi upgrade\` to update.`,
+    ...breaking ? [
+      `  This crosses a minor version \u2014 read UPGRADE.md before you do:`,
+      `  https://github.com/nstfkc/gemi/blob/main/UPGRADE.md`
+    ] : [],
+    ""
+  ].join(`
+`);
+}
+async function checkForUpdate(options) {
+  const { rootDir, env = process.env, timeoutMs, fetchImpl } = options;
+  if (!shouldCheckForUpdate(env))
+    return null;
+  const installed = readInstalledVersion(rootDir);
+  if (!installed)
+    return null;
+  const published = await fetchNewestPublished(installed, {
+    timeoutMs,
+    fetchImpl
+  });
+  if (!published)
+    return null;
+  return formatUpdateNotice(installed, published);
+}
+function reportUpdate(options, log = console.log) {
+  return checkForUpdate(options).then((notice) => {
+    if (notice)
+      log(notice);
+  }).catch(() => {});
+}
+
+// bin/upgrade.ts
+import { existsSync as existsSync7, readFileSync as readFileSync4 } from "fs";
+import path6 from "path";
+
+// bin/install-skill.ts
+import { createHash as createHash2 } from "crypto";
+import {
+  cpSync,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync3,
+  renameSync,
+  rmSync as rmSync2,
+  writeFileSync as writeFileSync2
+} from "fs";
+import path5 from "path";
+var SKILL_NAME = "gemi-react-best-practices";
+function skillSourceDir(gemiPackageDir) {
+  return path5.join(gemiPackageDir, "skills", SKILL_NAME);
+}
+function skillTargetDir(rootDir) {
+  return path5.join(rootDir, ".agents", "skills", SKILL_NAME);
+}
+function lockPath(rootDir) {
+  return path5.join(rootDir, ".agents", ".skill-lock.json");
+}
+function isSkillInstalled(rootDir) {
+  return existsSync6(path5.join(skillTargetDir(rootDir), "SKILL.md"));
+}
+function hashDirectory(dir) {
+  const hash = createHash2("sha1");
+  const walk3 = (current, prefix) => {
+    const entries = readdirSync3(current, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const entry of entries) {
+      const full = path5.join(current, entry.name);
+      const relative3 = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk3(full, relative3);
+      } else if (entry.isFile()) {
+        hash.update(relative3);
+        hash.update("\x00");
+        hash.update(readFileSync3(full));
+        hash.update("\x00");
+      }
+    }
+  };
+  walk3(dir, "");
+  return hash.digest("hex");
+}
+function readLock(rootDir) {
+  const empty = { version: 3, skills: {} };
+  const file = lockPath(rootDir);
+  if (!existsSync6(file))
+    return empty;
+  try {
+    const parsed = JSON.parse(readFileSync3(file, "utf8"));
+    if (!parsed || typeof parsed !== "object")
+      return empty;
+    return {
+      ...parsed,
+      version: typeof parsed.version === "number" ? parsed.version : 3,
+      skills: parsed.skills && typeof parsed.skills === "object" ? parsed.skills : {}
+    };
+  } catch {
+    return empty;
+  }
+}
+function writeLock(rootDir, lock) {
+  mkdirSync2(path5.dirname(lockPath(rootDir)), { recursive: true });
+  writeFileSync2(lockPath(rootDir), `${JSON.stringify(lock, null, 2)}
+`);
+}
+function quarantineUnreadableLock(rootDir) {
+  const file = lockPath(rootDir);
+  if (!existsSync6(file))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync3(file, "utf8"));
+    if (parsed && typeof parsed === "object")
+      return null;
+  } catch {}
+  const quarantined = `${file}.corrupt`;
+  renameSync(file, quarantined);
+  return quarantined;
+}
+function installSkill(options) {
+  const { error = console.error } = options;
+  try {
+    return install(options);
+  } catch (cause) {
+    error(`Could not install the \`${SKILL_NAME}\` skill: ` + `${cause instanceof Error ? cause.message : String(cause)}`);
+    return 1;
+  }
+}
+function install(options) {
+  const {
+    rootDir,
+    force = false,
+    onlyIfInstalled = false,
+    log = console.log,
+    error = console.error,
+    now = () => new Date().toISOString()
+  } = options;
+  if (onlyIfInstalled && !isSkillInstalled(rootDir))
+    return 0;
+  const packageDir = findGemiPackageDir(rootDir);
+  if (!packageDir) {
+    error(`Could not find an installed gemi under ${rootDir}. Run this from the ` + `root of a gemi project (one with \`gemi\` in its node_modules).`);
+    return 1;
+  }
+  const source = skillSourceDir(packageDir);
+  if (!existsSync6(path5.join(source, "SKILL.md"))) {
+    error(`The installed gemi does not ship the \`${SKILL_NAME}\` skill (looked in ` + `${source}). It was added in a later release \u2014 run \`gemi upgrade\` first.`);
+    return 1;
+  }
+  const target = skillTargetDir(rootDir);
+  const lock = readLock(rootDir);
+  const recorded = lock.skills[SKILL_NAME];
+  const existing = existsSync6(target) ? hashDirectory(target) : null;
+  if (existing !== null && !force) {
+    if (!recorded) {
+      error(`${path5.relative(rootDir, target) || target} already exists and was not ` + `installed by \`gemi install-skill\`. Re-run with --force to replace it.`);
+      return 1;
+    }
+    if (recorded.skillFolderHash !== existing) {
+      error(`${path5.relative(rootDir, target) || target} has local edits. Re-run with ` + `--force to discard them and install the version shipped with gemi.`);
+      return 1;
+    }
+  }
+  const version = readInstalledVersion(rootDir) ?? undefined;
+  const sourceHash = hashDirectory(source);
+  if (existing !== null && existing === sourceHash) {
+    log(`${SKILL_NAME} is already up to date${version ? ` (gemi ${version})` : ""}.`);
+    return 0;
+  }
+  mkdirSync2(path5.dirname(target), { recursive: true });
+  const staging = `${target}.tmp-${process.pid}`;
+  rmSync2(staging, { recursive: true, force: true });
+  try {
+    cpSync(source, staging, { recursive: true });
+    rmSync2(target, { recursive: true, force: true });
+    renameSync(staging, target);
+  } finally {
+    rmSync2(staging, { recursive: true, force: true });
+  }
+  const timestamp = now();
+  lock.skills[SKILL_NAME] = {
+    source: "gemi",
+    sourceType: "npm",
+    skillPath: `skills/${SKILL_NAME}/SKILL.md`,
+    skillFolderHash: sourceHash,
+    ...version ? { version } : {},
+    installedAt: recorded?.installedAt ?? timestamp,
+    updatedAt: timestamp
+  };
+  const quarantined = quarantineUnreadableLock(rootDir);
+  if (quarantined) {
+    log(`${path5.relative(rootDir, lockPath(rootDir))} could not be parsed and was ` + `kept as ${path5.basename(quarantined)}; a fresh one was written.`);
+  }
+  writeLock(rootDir, lock);
+  const where = path5.relative(rootDir, target) || target;
+  log(existing === null ? `Installed ${SKILL_NAME} to ${where}${version ? ` (gemi ${version})` : ""}.` : `Updated ${SKILL_NAME} in ${where}${version ? ` (gemi ${version})` : ""}.`);
+  return 0;
+}
+
+// bin/upgrade.ts
+var LOCKFILES = [
+  ["bun", ["bun.lock", "bun.lockb"]],
+  ["pnpm", ["pnpm-lock.yaml"]],
+  ["yarn", ["yarn.lock"]],
+  ["npm", ["package-lock.json"]]
+];
+function detectPackageManager(rootDir) {
+  let dir = path6.resolve(rootDir);
+  while (true) {
+    for (const [manager, files] of LOCKFILES) {
+      if (files.some((file) => existsSync7(path6.join(dir, file))))
+        return manager;
+    }
+    const parent = path6.dirname(dir);
+    if (parent === dir)
+      return "bun";
+    dir = parent;
+  }
+}
+function dependencyKind(dir) {
+  const manifestPath = path6.join(dir, "package.json");
+  if (!existsSync7(manifestPath))
+    return null;
+  try {
+    const manifest = JSON.parse(readFileSync4(manifestPath, "utf8"));
+    if (manifest?.dependencies?.gemi)
+      return "dependencies";
+    if (manifest?.devDependencies?.gemi)
+      return "devDependencies";
+    return null;
+  } catch {
+    return null;
+  }
+}
+function findDeclaringDir(rootDir) {
+  let dir = path6.resolve(rootDir);
+  while (true) {
+    const kind = dependencyKind(dir);
+    if (kind)
+      return { dir, kind };
+    const parent = path6.dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
+function installCommand(manager, spec, kind) {
+  const dev = kind === "devDependencies";
+  switch (manager) {
+    case "bun":
+      return ["bun", "add", ...dev ? ["--dev"] : [], spec];
+    case "pnpm":
+      return ["pnpm", "add", ...dev ? ["--save-dev"] : [], spec];
+    case "yarn":
+      return ["yarn", "add", ...dev ? ["--dev"] : [], spec];
+    case "npm":
+      return ["npm", "install", ...dev ? ["--save-dev"] : ["--save-prod"], spec];
+  }
+}
+async function defaultSpawn(cmd, cwd) {
+  const proc = Bun.spawn({
+    cmd,
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit"
+  });
+  await proc.exited;
+  return proc.exitCode ?? 1;
+}
+async function runUpgrade(options) {
+  const {
+    rootDir,
+    target,
+    dryRun = false,
+    fetchImpl,
+    log = console.log,
+    error = console.error,
+    spawn = defaultSpawn,
+    installSkillImpl = installSkill
+  } = options;
+  const installed = readInstalledVersion(rootDir);
+  if (!installed) {
+    error(`Could not find an installed gemi under ${rootDir}. Run this from the ` + `root of a gemi project (one with \`gemi\` in its node_modules).`);
+    return 1;
+  }
+  const declaring = findDeclaringDir(rootDir);
+  if (!declaring) {
+    error(`No \`package.json\` at or above ${rootDir} declares \`gemi\` as a ` + `dependency, so there is nothing to upgrade. Run this from the ` + `directory whose manifest depends on gemi.`);
+    return 1;
+  }
+  const { dir: installDir, kind } = declaring;
+  const explicitVersion = target && parseVersion(target) ? target : null;
+  const tag = explicitVersion ? null : target;
+  let resolved = explicitVersion;
+  if (!resolved) {
+    log(`Resolving gemi@${tag ?? channelFor(installed)}...`);
+    resolved = tag ? await fetchPublishedVersion(tag, { timeoutMs: 1e4, fetchImpl }) : await fetchNewestPublished(installed, { timeoutMs: 1e4, fetchImpl });
+    if (!resolved) {
+      error(`Could not resolve \`gemi@${tag ?? channelFor(installed)}\` from the npm ` + `registry. Check your connection, or pass an explicit version: ` + `\`gemi upgrade 0.59.0\`.`);
+      return 1;
+    }
+  }
+  const direction = compareVersions(resolved, installed);
+  if (direction === 0) {
+    log(explicitVersion ? `gemi is already at ${installed}.` : tag ? `gemi ${installed} is already the newest release on \`${tag}\`.` : `gemi ${installed} is already the newest release published.`);
+    return 0;
+  }
+  const spec = `gemi@${resolved}`;
+  const cmd = installCommand(detectPackageManager(installDir), spec, kind);
+  log(direction > 0 ? `Upgrading gemi ${installed} \u2192 ${resolved}` : `Downgrading gemi ${installed} \u2192 ${resolved}`);
+  const from = parseVersion(installed);
+  const to = parseVersion(resolved);
+  if (from && to && (from.core[0] !== to.core[0] || from.core[1] !== to.core[1])) {
+    log(`
+This crosses a minor version. UPGRADE.md documents what each one ` + `requires \u2014 read it before running your app:
+` + `  https://github.com/nstfkc/gemi/blob/main/UPGRADE.md
+`);
+  }
+  if (dryRun) {
+    log(`Would run: ${cmd.join(" ")}`);
+    return 0;
+  }
+  const code = await spawn(cmd, installDir);
+  if (code !== 0) {
+    error(`
+\`${cmd.join(" ")}\` failed with exit code ${code}.`);
+    return code;
+  }
+  log(`
+gemi is now ${resolved}.`);
+  installSkillImpl({ rootDir, onlyIfInstalled: true, log, error });
+  return 0;
+}
+
 // bin/gemi.ts
 function appPreloadArgs(appDir) {
-  const preloadPath = path4.join(appDir, "preload.ts");
-  return existsSync5(preloadPath) ? ["--preload", preloadPath] : [];
+  const preloadPath = path7.join(appDir, "preload.ts");
+  return existsSync8(preloadPath) ? ["--preload", preloadPath] : [];
 }
 program.command("dev").action(async () => {
   console.log("Starting dev server...");
-  const rootDir = path4.resolve(process.cwd());
-  const appDir = path4.join(rootDir, "app");
+  const rootDir = path7.resolve(process.cwd());
+  const appDir = path7.join(rootDir, "app");
   process.env.NODE_ENV = "development";
   Bun.spawn({
     cmd: [
@@ -39794,11 +40263,12 @@ program.command("dev").action(async () => {
       "--preload",
       "gemi/bun/preload",
       ...appPreloadArgs(appDir),
-      `${path4.join(appDir, "server.ts")}`
+      `${path7.join(appDir, "server.ts")}`
     ],
     stdout: "inherit",
     stderr: "inherit"
   });
+  reportUpdate({ rootDir });
 });
 program.command("build").action(async () => {
   if (process.env.GEMI_BUILD_PROD !== "1") {
@@ -39812,8 +40282,8 @@ program.command("build").action(async () => {
     process.exit(proc.exitCode ?? 0);
   }
   process.env.NODE_ENV = "production";
-  const rootDir = path4.resolve(process.cwd());
-  const appDir = path4.join(rootDir, "app");
+  const rootDir = path7.resolve(process.cwd());
+  const appDir = path7.join(rootDir, "app");
   const config = await loadGemiConfig(rootDir);
   const input = await createRollupInput_default(appDir);
   process.env.GEMI_INPUT = JSON.stringify(input);
@@ -39849,8 +40319,8 @@ program.command("build").action(async () => {
 });
 program.command("start").action(async () => {
   console.log("Starting server...");
-  const rootDir = path4.resolve(process.cwd());
-  const appDir = path4.join(rootDir, "app");
+  const rootDir = path7.resolve(process.cwd());
+  const appDir = path7.join(rootDir, "app");
   const proc = Bun.spawn({
     cmd: [
       "bun",
@@ -39867,8 +40337,8 @@ program.command("start").action(async () => {
 });
 program.enablePositionalOptions();
 program.command("run").description("Run a Command from app/commands. Everything after the name is the " + "command's own, including its flags. Omit the name to list them").argument("[name]", "The command's name").argument("[args...]", "Passed through to the command untouched").passThroughOptions().action(async (name, args) => {
-  const rootDir = path4.resolve(process.cwd());
-  const appDir = path4.join(rootDir, "app");
+  const rootDir = path7.resolve(process.cwd());
+  const appDir = path7.join(rootDir, "app");
   let entry;
   try {
     entry = Bun.resolveSync("gemi/console/run", rootDir);
@@ -39895,10 +40365,24 @@ program.command("run").description("Run a Command from app/commands. Everything
   process.exit(proc.exitCode ?? 1);
 });
 program.command("migrate").description("Migrate an app from the 0.42 service-provider layout to the config + " + "container layout, flagging APIs retired since").option("--dry-run", "Print the plan without writing anything").action(async (options) => {
-  const rootDir = path4.resolve(process.cwd());
+  const rootDir = path7.resolve(process.cwd());
   console.log(options.dryRun ? `Planning migration of ${rootDir}...` : `Migrating ${rootDir}...`);
   await runMigrate({ rootDir, dryRun: options.dryRun });
 });
+program.command("upgrade").description("Upgrade the `gemi` package. With no argument it moves to the newest " + "release on the channel you are already on \u2014 `rc` for a release " + "candidate, `latest` otherwise \u2014 so an rc is never 'upgraded' backwards " + "onto the older stable release").argument("[target]", "A version (`0.59.0`) to pin or roll back to, or a dist-tag (`rc`, " + "`latest`). Defaults to the current channel's tag").option("--dry-run", "Resolve the version and print the install command, run nothing").action(async (target, options) => {
+  const code = await runUpgrade({
+    rootDir: path7.resolve(process.cwd()),
+    target,
+    dryRun: options.dryRun
+  });
+  process.exit(code);
+});
+program.command("install-skill").description(`Install the \`${SKILL_NAME}\` agent skill that ships with your gemi into ` + `.agents/skills/. \`gemi upgrade\` re-runs this afterwards, so the rules an ` + `agent reads stay pinned to the gemi the app actually runs`).option("--force", "Replace an installed copy that has local edits, or one this command did not write").action(async (options) => {
+  process.exit(installSkill({
+    rootDir: path7.resolve(process.cwd()),
+    force: options.force
+  }));
+});
 var check = program.command("check").description("Checks that can be run in CI, on a project that is not running");
 check.command("models").description("Report policied model classes that the modules `Kernel.models` declares " + "do not register \u2014 the leak `Kernel.models` cannot see, because it can " + "only audit the modules it is handed. Imports every file it walks, so a " + "model file that does work when imported does it here; use --ignore").option("--dir <path>", "Model directory to walk, relative to the project root", "app/models").option("--models <paths>", "Module paths to register from, instead of reading `Kernel.models` \u2014 for " + "a Kernel whose import graph needs build-time transforms this command " + "cannot apply. Comma-separated, and repeatable", (value, previous) => [
   ...previous,
@@ -39909,7 +40393,7 @@ check.command("models").description("Report policied model classes that the modu
 ], []).action(async (options) => {
   try {
     const report2 = await checkModels({
-      rootDir: path4.resolve(process.cwd()),
+      rootDir: path7.resolve(process.cwd()),
       modelsDir: options.dir,
       ignore: options.ignore,
       models: options.models
@@ -39938,5 +40422,5 @@ program.command("app:route-manifest").action(async () => {
 });
 program.parse();
 
-//# debugId=FD52AD3855B4935264756E2164756E21
+//# debugId=A013F2EE91F38DEE64756E2164756E21
 //# sourceMappingURL=gemi.js.map