@stacksjs/actions 0.70.162 → 0.70.164

package/README.md

@@ -49,7 +49,7 @@ For help, discussion about best practices, or any other conversation that would
 
 For casual chit-chat with others using this package:
 
-[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+[Join the Stacks Discord Server](https://stacksjs.com/discord)
 
 ## 📄 License
 

package/dist/bump.js

@@ -138,6 +138,11 @@ if (!isDryRun && existsSync(p.projectPath("bun.lock"))) {
     writeFileSync(lockPath, previousLock);
     throw error;
   }
+  const expectedLockfileVersion = 1, versionMatch = readFileSync(lockPath, "utf8").match(/"lockfileVersion"\s*:\s*(\d+)/), producedVersion = versionMatch ? Number(versionMatch[1]) : null;
+  if (producedVersion !== expectedLockfileVersion) {
+    writeFileSync(lockPath, previousLock);
+    throw Error(`Release aborted: regenerating bun.lock produced lockfileVersion ${producedVersion ?? "unknown"}, but CI's Bun (1.3.x) requires v${expectedLockfileVersion}. You are releasing with a newer Bun (1.4.x writes v2). Re-run the release with Bun 1.3.x (e.g. via \`bunx bun@1.3.14\`) so CI can parse the lockfile.`);
+  }
 }
 function pinMetaCoreDeps(version) {
   const metaPath = p.frameworkPath("core/package.json"), meta = JSON.parse(readFileSync(metaPath, "utf-8"));

package/dist/deploy/index.js

@@ -1014,7 +1014,7 @@ SVCEOF`,
             } else
               smtpSpinner.fail(`No Pantry-provided ${MAIL_TARGET_PLATFORM} mail binary found. Release ${MAIL_PACKAGE_DOMAIN}, then run the Pantry binary sync for that package.`);
           } else {
-            const smtpServerSrc = resolvePath(p.projectPath("storage/framework/core/cloud/src/imap/smtp-server.ts")), bundleOutDir = joinPath(p.projectPath(), ".stacks/tmp/smtp-bundle");
+            const smtpServerSrc = resolvePath(p.projectPath("storage/framework/core/cloud/src/imap/smtp-server.ts")), bundleOutDir = p.frameworkRuntimePath("tmp/smtp-bundle");
             execSync(`bun build ${smtpServerSrc} --target=bun --outdir=${bundleOutDir}`, { stdio: "pipe" });
             const bundlePath = joinPath(bundleOutDir, "smtp-server.js");
             if (smtpFileExists(bundlePath)) {

package/dist/dev/dashboard.js

@@ -323,7 +323,7 @@ if (!proxyStarted)
       console.warn("[Dashboard] Reverse proxy failed:", err);
     return !1;
   });
-const dashboardHttpsUrl = dashboardDomain ? `https://${dashboardDomain}` : null, dashboardLocalUrl = `http://localhost:${dashboardPort}`, initialUrl = dashboardHttpsUrl && proxyStarted ? `${dashboardHttpsUrl}/` : `${dashboardLocalUrl}/`, elapsedMs = (Bun.nanoseconds() - startTime) / 1e6;
+const dashboardHttpsUrl = dashboardDomain ? `https://${dashboardDomain}` : null, dashboardLocalUrl = `http://localhost:${dashboardPort}`, initialUrl = dashboardHttpsUrl && proxyStarted ? `${dashboardHttpsUrl}/` : `${dashboardLocalUrl}/`, nativeWindowUrl = `${dashboardLocalUrl}/`, elapsedMs = (Bun.nanoseconds() - startTime) / 1e6;
 console.log();
 console.log(`  ${bold(cyan("stacks dashboard"))}`);
 console.log();
@@ -396,7 +396,7 @@ if (createApp) {
     await new Promise(() => {});
   }
   const app = createApp({
-    url: initialUrl,
+    url: nativeWindowUrl,
     quiet: !verbose,
     ...craftBinaryPath && { craftPath: craftBinaryPath },
     window: {

package/dist/generate/index.d.ts

@@ -32,5 +32,13 @@ export declare function generateTypes(options?: GeneratorOptions): Promise<void>
 export declare function watchTypes(options?: GeneratorOptions): Promise<void>;
 export declare function generatePantryConfig(): void;
 export declare function generateSeeder(): Promise<void>;
+/**
+ * Drops a `.framework` symlink in the project root pointing at
+ * `storage/framework`, so core developers can `cd .framework` instead of typing
+ * the full path. Purely a convenience; nothing in the framework depends on it.
+ *
+ * It used to be called `.stacks`, which now collides with the pre-relocation
+ * name of the runtime scratch directory (see `ensureRuntimeDirectories`).
+ */
 export declare function generateCoreSymlink(): Promise<void>;
 export declare function generateOpenApiSpec(): Promise<void>;

package/dist/generate/index.js

@@ -149,7 +149,10 @@ export function generatePantryConfig() {
 }
 export async function generateSeeder() {}
 export async function generateCoreSymlink() {
-  await runCommand(`ln -s ${frameworkPath()} ${projectPath(".stacks")}`);
+  const link = projectPath(".framework");
+  if (fs.existsSync(link))
+    await runCommand(`rm -f ${link}`);
+  await runCommand(`ln -s ${frameworkPath()} ${link}`);
 }
 export async function generateOpenApiSpec() {
   const { generateOpenApi } = await import("@stacksjs/api");

package/dist/helpers/utils.js

@@ -29,8 +29,10 @@ export function publishedActionCandidates(action, packageRoot) {
 export function developmentConditionForProject(projectRoot) {
   return existsSync(join(projectRoot, "storage/framework/core")) && existsSync(join(projectRoot, "node_modules/@stacksjs/env/src/index.ts")) ? "--conditions development" : "";
 }
-async function resolveActionFile(action) {
+async function resolveActionFile(action, projectRoot) {
   const candidates = [];
+  if (projectRoot)
+    candidates.push(join(projectRoot, `storage/framework/core/actions/src/${action}.ts`));
   candidates.push(p.actionsPath(`src/${action}.ts`));
   candidates.push(...publishedActionCandidates(action));
   for (const candidate of candidates)
@@ -60,8 +62,9 @@ export async function runAction(action, options) {
     } catch (error) {
       return err(`Failed to start dev server: ${error}`);
     }
-  if (!(action.includes("/") || ["dev", "build", "install", "upgrade", "migrate"].some((prefix) => action.startsWith(prefix)))) {
-    const glob = new Bun.Glob("**/*.{ts,js}"), scanOptions = { cwd: p.userActionsPath(), onlyFiles: !0, absolute: !0 }, matchingFiles = [], basePath = p.userActionsPath();
+  const isLikelyCoreAction = action.includes("/") || ["dev", "build", "install", "upgrade", "migrate"].some((prefix) => action.startsWith(prefix)), userActionsBase = options?.cwd ? join(String(options.cwd), "app/Actions") : p.userActionsPath();
+  if (!isLikelyCoreAction && existsSync(userActionsBase)) {
+    const glob = new Bun.Glob("**/*.{ts,js}"), scanOptions = { cwd: userActionsBase, onlyFiles: !0, absolute: !0 }, matchingFiles = [], basePath = userActionsBase;
     for await (const file of glob.scan(scanOptions)) {
       if (file.replace(`${basePath}/`, "").replace(/\.(ts|js)$/, "") === action || file.endsWith(`${action}.ts`) || file.endsWith(`${action}.js`)) {
         log.debug(`[action] Resolved: ${action} \u2192 ${file}`);
@@ -78,7 +81,7 @@ export async function runAction(action, options) {
         }
       } catch (error) {}
   }
-  const path = await resolveActionFile(action);
+  const path = await resolveActionFile(action, options?.cwd ? String(options.cwd) : void 0);
   if (!path)
     return err(`Action '${action}' not found in storage/framework/core/actions/src or @stacksjs/actions`);
   log.debug(`[action] Resolved: ${action} \u2192 ${path}`);

package/dist/upgrade/catalog.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Every dependency name a manifest pins to `catalog:`.
+ *
+ * Bun also accepts the named form (`catalog:react19`); those resolve from a
+ * separate `catalogs` map rather than the default catalog, so we deliberately
+ * match only the bare default protocol here.
+ */
+export declare function collectCatalogReferences(manifests: PackageManifest[]): string[];
+/**
+ * Read a catalog off a manifest, accepting either shape Bun supports: a
+ * top-level `catalog` field, or `workspaces.catalog` on the object form.
+ */
+export declare function readCatalogField(manifest: PackageManifest | null | undefined): Record<string, string>;
+/**
+ * Merge the upstream catalog into the app's own, restricted to what the
+ * vendored tree references.
+ *
+ * User-authored entries survive untouched: we only write keys that appear in
+ * `referenced`, so a catalog entry the app added for its own packages is never
+ * clobbered by an upgrade.
+ */
+export declare function mergeCatalog(current: Record<string, string>, upstream: Record<string, string>, referenced: string[]): CatalogMergeResult;
+/** Parse a `package.json`, returning null rather than throwing on bad input. */
+export declare function readManifest(path: string): PackageManifest | null;
+/**
+ * Walk a synced tree for workspace manifests. Depth is bounded because the
+ * framework nests packages at most a few levels deep, and an unbounded walk
+ * over a vendored tree is needlessly expensive on every upgrade.
+ */
+export declare function findWorkspaceManifests(root: string, maxDepth?: number): string[];
+/**
+ * Fetch the upstream catalog for a GitHub-sourced upgrade.
+ *
+ * We hit the raw root manifest directly rather than re-downloading a tarball
+ * we've already extracted the interesting parts of. Failure is non-fatal: the
+ * caller falls back to leaving the existing catalog alone.
+ */
+export declare function fetchUpstreamCatalog(ref: string): Promise<Record<string, string>>;
+/**
+ * Mirror the upstream catalog into the app's root manifest so the vendored
+ * workspace members resolve. Returns null when there is nothing to do.
+ */
+export declare function reconcileWorkspaceCatalog(options: ReconcileCatalogOptions): Promise<CatalogMergeResult | null>;
+export declare interface PackageManifest {
+  catalog?: Record<string, string>
+  workspaces?: string[] | { catalog?: Record<string, string> }
+  [field: string]: unknown
+}
+export declare interface CatalogMergeResult {
+  catalog: Record<string, string>
+  added: string[]
+  updated: string[]
+  missing: string[]
+}
+export declare interface ReconcileCatalogOptions {
+  projectRoot: string
+  frameworkRoot: string
+  localStacksRoot?: string | null
+  ref?: string
+}

package/dist/upgrade/catalog.js

@@ -0,0 +1,113 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const CATALOG_PROTOCOL = "catalog:", DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies"
+], MANIFEST_SCAN_SKIP = new Set(["node_modules", "dist", ".git", ".cache", "cache"]);
+export function collectCatalogReferences(manifests) {
+  const names = new Set;
+  for (const manifest of manifests)
+    for (const field of DEPENDENCY_FIELDS) {
+      const deps = manifest[field];
+      if (!deps || typeof deps !== "object")
+        continue;
+      for (const [name, range] of Object.entries(deps))
+        if (range === CATALOG_PROTOCOL)
+          names.add(name);
+    }
+  return [...names].sort();
+}
+export function readCatalogField(manifest) {
+  if (!manifest)
+    return {};
+  if (manifest.catalog && typeof manifest.catalog === "object")
+    return { ...manifest.catalog };
+  const workspaces = manifest.workspaces;
+  if (workspaces && !Array.isArray(workspaces) && workspaces.catalog)
+    return { ...workspaces.catalog };
+  return {};
+}
+export function mergeCatalog(current, upstream, referenced) {
+  const catalog = { ...current }, added = [], updated = [], missing = [];
+  for (const name of referenced) {
+    const version = upstream[name];
+    if (!version) {
+      if (!(name in catalog))
+        missing.push(name);
+      continue;
+    }
+    if (!(name in catalog)) {
+      catalog[name] = version;
+      added.push(name);
+      continue;
+    }
+    if (catalog[name] !== version) {
+      catalog[name] = version;
+      updated.push(name);
+    }
+  }
+  return { catalog: sortKeys(catalog), added, updated, missing };
+}
+function sortKeys(record) {
+  return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function readManifest(path) {
+  try {
+    if (!existsSync(path))
+      return null;
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+export function findWorkspaceManifests(root, maxDepth = 4) {
+  const found = [], walk = (dir, depth) => {
+    if (depth > maxDepth || !existsSync(dir))
+      return;
+    const manifest = join(dir, "package.json");
+    if (existsSync(manifest))
+      found.push(manifest);
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: !0 });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory())
+        continue;
+      if (entry.name.startsWith(".") || MANIFEST_SCAN_SKIP.has(entry.name))
+        continue;
+      walk(join(dir, entry.name), depth + 1);
+    }
+  };
+  walk(root, 0);
+  return found;
+}
+export async function fetchUpstreamCatalog(ref) {
+  try {
+    const response = await fetch(`https://raw.githubusercontent.com/stacksjs/stacks/${ref}/package.json`);
+    if (!response.ok)
+      return {};
+    return readCatalogField(await response.json());
+  } catch {
+    return {};
+  }
+}
+export async function reconcileWorkspaceCatalog(options) {
+  const rootManifestPath = join(options.projectRoot, "package.json"), rootManifest = readManifest(rootManifestPath);
+  if (!rootManifest)
+    return null;
+  const manifests = findWorkspaceManifests(options.frameworkRoot).map(readManifest).filter((manifest) => manifest !== null), referenced = collectCatalogReferences(manifests);
+  if (referenced.length === 0)
+    return null;
+  const upstream = options.localStacksRoot ? readCatalogField(readManifest(join(options.localStacksRoot, "package.json"))) : await fetchUpstreamCatalog(options.ref || "main"), result = mergeCatalog(readCatalogField(rootManifest), upstream, referenced);
+  if (result.added.length === 0 && result.updated.length === 0)
+    return result;
+  rootManifest.catalog = result.catalog;
+  await Bun.write(rootManifestPath, `${JSON.stringify(rootManifest, null, 2)}
+`);
+  return result;
+}

package/dist/upgrade/framework-hooks.d.ts

@@ -1,3 +1,27 @@
+/**
+ * A `pantry.lock` is the marker: it only exists once pantry owns the graph.
+ *
+ * Getting this wrong is not cosmetic. Running `bun install` in a pantry app
+ * refreshes a `node_modules` tree that nothing resolves against, so the
+ * upgrade reports success while the app keeps importing the stale copies in
+ * `pantry/` - which surfaces later as missing exports from packages the
+ * manifest claims are current.
+ */
+export declare function detectDependencyInstaller(hasPantryLock: boolean): DependencyInstaller;
+/**
+ * Build the refresh argv. Both installers spell the "re-resolve everything"
+ * flag `--force`, so the shape is the same either way.
+ */
+export declare function resolveDependencyRefreshCommand(options: {
+  installer: DependencyInstaller
+  bunExecutable: string
+  pantryExecutable: string
+}): string[];
+/**
+ * Pick the first pantry binary that exists, falling back to a bare `pantry`
+ * so a PATH install still works. `exists` is injected to keep this testable.
+ */
+export declare function resolvePantryExecutable(candidates: string[], exists: (path: string) => boolean): string;
 /**
  * The first upgrade process records the real file changes, then restarts itself
  * after replacing its own framework code. The restarted process sees the
@@ -14,8 +38,8 @@ export declare function shouldRefreshPostSyncDependencies(corePackageChanged: bo
 /**
  * Fully refresh dependencies after replacing vendored workspace manifests.
  *
- * A plain `bun install` may reuse the existing nested package placement and
- * leave a lockfile that changes in a clean checkout. `--force` makes Bun
+ * A plain install may reuse the existing nested package placement and leave a
+ * lockfile that changes in a clean checkout. `--force` makes the installer
  * resolve the complete workspace graph so the resulting lockfile is valid for
  * subsequent frozen installs.
  */
@@ -45,8 +69,17 @@ declare interface PostSyncMigrationOptions {
   spawn: PostSyncSpawn
 }
 declare interface PostSyncDependencyOptions {
-  bunExecutable: string
+  cmd: string[]
   projectRoot: string
   spawn: PostSyncSpawn
 }
 declare type PostSyncSpawn = (options: PostSyncSpawnOptions) => { exited: Promise<number> }
+/**
+ * Which installer owns the project's dependency graph.
+ *
+ * Stacks apps come in two flavours. The default resolves third-party packages
+ * from `node_modules` and is installed by Bun. A pantry app instead installs
+ * into `pantry/` and points tsconfig's catch-all path mapping at it, so that
+ * directory - not `node_modules` - is what module resolution actually reads.
+ */
+export type DependencyInstaller = 'bun' | 'pantry';

package/dist/upgrade/framework-hooks.js

@@ -1,3 +1,15 @@
+export function detectDependencyInstaller(hasPantryLock) {
+  return hasPantryLock ? "pantry" : "bun";
+}
+export function resolveDependencyRefreshCommand(options) {
+  return [options.installer === "pantry" ? options.pantryExecutable : options.bunExecutable, "install", "--force"];
+}
+export function resolvePantryExecutable(candidates, exists) {
+  for (const candidate of candidates)
+    if (candidate && exists(candidate))
+      return candidate;
+  return "pantry";
+}
 export function shouldRunPostSyncHooks(changeCount, alreadyRestarted) {
   return changeCount > 0 || alreadyRestarted;
 }
@@ -6,7 +18,7 @@ export function shouldRefreshPostSyncDependencies(corePackageChanged, alreadyRes
 }
 export async function runPostSyncDependencyRefresh(options) {
   const code = await options.spawn({
-    cmd: [options.bunExecutable, "install", "--force"],
+    cmd: options.cmd,
     cwd: options.projectRoot,
     stdin: "ignore",
     stdout: "inherit",

package/dist/upgrade/framework-utils.d.ts

@@ -2,17 +2,35 @@
  * Resolve the target channel and git ref from CLI options and persisted channel.
  * Priority: --version > --canary > --stable > persisted channel
  *
- * Branch model: `main` is the bleeding-edge "dump everything" branch; `stable`
- * is the vetted branch that PRs are merged into from `main` once main is proven.
- * So the `stable` channel tracks the `stable` branch (vetted) and the `canary`
- * channel tracks the `main` branch (bleeding edge). A pinned `--version` still
- * resolves to the matching `vX` tag.
+ * Release model: `main` is the bleeding-edge "dump everything" branch, and each
+ * release is cut as a `vX.Y.Z` git tag (see `.github/workflows/release.yml`,
+ * which triggers on `push: tags: ['v*']`). There is deliberately no long-lived
+ * `stable` branch. So the `canary` channel tracks the `main` branch (bleeding
+ * edge) and the `stable` channel tracks the latest published `vX.Y.Z` tag —
+ * passed in as `latestStableRef` because resolving it needs the network, which
+ * this pure function stays free of. A pinned `--version` resolves directly to
+ * the matching `vX` tag.
  */
 export declare function resolveUpgradeContext(options: {
   version?: string
   canary?: boolean
   stable?: boolean
-}, currentChannel: 'stable' | 'canary'): UpgradeContext;
+}, currentChannel: 'stable' | 'canary', latestStableRef: string): UpgradeContext;
+/**
+ * Pick the highest stable release tag from a list of tag names. Only clean
+ * `vMAJOR.MINOR.PATCH` tags qualify — pre-releases (`v1.0.0-beta.1`), annotated
+ * deref entries (`…^{}`), and non-version tags are ignored. Returns null when
+ * nothing qualifies.
+ */
+export declare function pickLatestStableTag(tags: string[]): string | null;
+/**
+ * Resolve the latest published stable release tag (e.g. `"v0.70.163"`) by
+ * listing the remote's `v*` tags. The stable channel installs this tag rather
+ * than a branch, because releases are cut as tags and no `stable` branch
+ * exists. Returns null if the tags can't be listed (offline / no git), letting
+ * the caller fall back to the currently-installed version.
+ */
+export declare function resolveLatestStableTag(): Promise<string | null>;
 /**
  * Build the gitit template string for a path under the stacks repo.
  * `subPath` is relative to the repo root (e.g. `storage/framework/core`).

package/dist/upgrade/framework-utils.js

@@ -2,17 +2,49 @@ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import process from "node:process";
-export function resolveUpgradeContext(options, currentChannel) {
+export function resolveUpgradeContext(options, currentChannel, latestStableRef) {
   const targetVersion = options.version;
   if (targetVersion)
     return { channel: "stable", ref: targetVersion.startsWith("v") ? targetVersion : `v${targetVersion}`, targetVersion };
   if (options.canary)
     return { channel: "canary", ref: "main" };
   if (options.stable)
-    return { channel: "stable", ref: "stable" };
+    return { channel: "stable", ref: latestStableRef };
   if (currentChannel === "canary")
     return { channel: "canary", ref: "main" };
-  return { channel: "stable", ref: "stable" };
+  return { channel: "stable", ref: latestStableRef };
+}
+function compareVersionParts(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+export function pickLatestStableTag(tags) {
+  const re = /^v(\d+)\.(\d+)\.(\d+)$/;
+  let best = null;
+  for (const tag of tags) {
+    const m = re.exec(tag.trim());
+    if (!m)
+      continue;
+    const parts = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (!best || compareVersionParts(parts, best.parts) > 0)
+      best = { tag: tag.trim(), parts };
+  }
+  return best?.tag ?? null;
+}
+export async function resolveLatestStableTag() {
+  try {
+    const proc = Bun.spawn({
+      cmd: ["git", "ls-remote", "--tags", "--refs", "https://github.com/stacksjs/stacks.git", "v*"],
+      stdout: "pipe",
+      stderr: "pipe"
+    }), out = await new Response(proc.stdout).text();
+    if (await proc.exited !== 0)
+      return null;
+    const tags = out.split(`
+`).map((line) => line.split("\t")[1]?.replace("refs/tags/", "")).filter((t) => !!t);
+    return pickLatestStableTag(tags);
+  } catch {
+    return null;
+  }
 }
 export function buildTemplateString(ref, subPath = "storage/framework/core") {
   return `github:stacksjs/stacks/${subPath}#${ref}`;

package/dist/upgrade/framework.js

@@ -15,6 +15,7 @@ import {
   readChannel,
   readSyncedVersion,
   readVersion,
+  resolveLatestStableTag,
   resolveSuccessMessage,
   resolveUpgradeContext,
   resolveUpgradeMessage,
@@ -25,7 +26,11 @@ import {
   writeChannel,
   writeSyncedVersion
 } from "./framework-utils";
+import { reconcileWorkspaceCatalog } from "./catalog";
 import {
+  detectDependencyInstaller,
+  resolveDependencyRefreshCommand,
+  resolvePantryExecutable,
   runPostSyncDependencyRefresh,
   runPostSyncMigration,
   shouldRefreshPostSyncDependencies,
@@ -43,7 +48,11 @@ if (!existsSync(p.projectPath("storage/framework/core"))) {
     noPostinstall: options.noPostinstall ?? options.postinstall === !1
   });
 }
-const channelFile = join(projectRoot, ".stacks-channel"), versionFile = join(projectRoot, ".stacks-version"), currentChannel = readChannel(channelFile), ctx = resolveUpgradeContext(options, currentChannel), corePkgPath = p.projectPath("storage/framework/core/buddy/package.json"), currentVersion = readVersion(corePkgPath), explicitLocal = options.from ? p.projectPath(options.from) : null, detectedLocal = explicitLocal ?? (shouldAutoDetectLocalStacks(options) ? detectLocalStacks(projectRoot) : null), usingLocal = !!detectedLocal;
+const channelFile = join(projectRoot, ".stacks-channel"), versionFile = join(projectRoot, ".stacks-version"), currentChannel = readChannel(channelFile), corePkgPath = p.projectPath("storage/framework/core/buddy/package.json"), currentVersion = readVersion(corePkgPath), willResolveStable = !options.version && !options.canary && (!!options.stable || currentChannel !== "canary");
+let latestStableRef = "";
+if (willResolveStable)
+  latestStableRef = await resolveLatestStableTag() ?? (currentVersion ? `v${currentVersion}` : "main");
+const ctx = resolveUpgradeContext(options, currentChannel, latestStableRef), explicitLocal = options.from ? p.projectPath(options.from) : null, detectedLocal = explicitLocal ?? (shouldAutoDetectLocalStacks(options) ? detectLocalStacks(projectRoot) : null), usingLocal = !!detectedLocal;
 console.log(resolveUpgradeMessage(ctx, currentChannel, !!options.stable));
 console.log(usingLocal ? `  source: local checkout at ${detectedLocal}` : `  source: github:stacksjs/stacks#${ctx.ref}`);
 if (options.dryRun) {
@@ -130,7 +139,7 @@ for (const { managed, summary } of perPath)
 const runHooks = !options.noPostinstall && options.postinstall !== !1;
 if (runHooks)
   try {
-    await runPostSyncHooks({ aggregate, perPath, projectRoot, alreadyRestarted });
+    await runPostSyncHooks({ aggregate, perPath, projectRoot, alreadyRestarted, localStacksRoot: detectedLocal, ref: ctx.ref });
   } catch (err) {
     console.error(`Post-sync hooks failed: ${err?.message || err}`);
     process.exit(ExitCode.FatalError);
@@ -303,13 +312,21 @@ async function getRemoteSha(context, fromLocal, stacksRoot) {
       return await head.exited === 0 && SHA_RE.test(h) ? h.toLowerCase() : null;
     }
     const proc = Bun.spawn({
-      cmd: ["git", "ls-remote", "https://github.com/stacksjs/stacks.git", `refs/heads/${context.ref}`],
+      cmd: [
+        "git",
+        "ls-remote",
+        "https://github.com/stacksjs/stacks.git",
+        `refs/heads/${context.ref}`,
+        `refs/tags/${context.ref}`,
+        `refs/tags/${context.ref}^{}`
+      ],
       stdout: "pipe",
       stderr: "pipe"
     }), out = await new Response(proc.stdout).text();
     if (await proc.exited !== 0)
       return null;
-    const m = out.match(/^([0-9a-f]{40})\s/i);
+    const lines = out.split(`
+`).filter(Boolean), m = (lines.find((l) => l.includes("^{}")) ?? lines[0])?.match(/^([0-9a-f]{40})\s/i);
     return m?.[1] ? m[1].toLowerCase() : null;
   } catch {
     return null;
@@ -400,7 +417,7 @@ async function syncRootFilesFromGitHub(ref) {
   }
 }
 async function runPostSyncHooks(args) {
-  const { aggregate, perPath, projectRoot, alreadyRestarted } = args, changeCount = aggregate.added + aggregate.changed + aggregate.removed;
+  const { aggregate, perPath, projectRoot, alreadyRestarted, localStacksRoot, ref } = args, changeCount = aggregate.added + aggregate.changed + aggregate.removed;
   if (!shouldRunPostSyncHooks(changeCount, alreadyRestarted)) {
     console.log("Nothing changed \u2014 skipping post-sync hooks.");
     return;
@@ -412,6 +429,25 @@ async function runPostSyncHooks(args) {
   } catch (err) {
     console.warn(`  auto-imports failed (non-fatal): ${err?.message || err}`);
   }
+  console.log("Reconciling workspace dependency catalog...");
+  try {
+    const result = await reconcileWorkspaceCatalog({
+      projectRoot,
+      frameworkRoot: join(projectRoot, "storage", "framework"),
+      localStacksRoot,
+      ref
+    });
+    if (!result)
+      console.log("  catalog: nothing to reconcile");
+    else if (result.added.length || result.updated.length)
+      console.log(`  catalog: +${result.added.length} added, ~${result.updated.length} updated`);
+    else
+      console.log("  catalog: up to date");
+    if (result?.missing.length)
+      console.warn(`  catalog: no upstream version for ${result.missing.join(", ")}`);
+  } catch (err) {
+    console.warn(`  catalog reconcile failed (non-fatal): ${err?.message || err}`);
+  }
   if (shouldRefreshPostSyncDependencies(perPath.some((entry) => {
     const { managed, summary } = entry;
     if (managed.isFile)
@@ -422,15 +458,20 @@ async function runPostSyncHooks(args) {
       return !1;
     return pkgJsonInTree(join(projectRoot, managed.localPath));
   }), alreadyRestarted)) {
-    console.log("Running `bun install` to refresh dependencies...");
+    const installer = detectDependencyInstaller(existsSync(join(projectRoot, "pantry.lock"))), cmd = resolveDependencyRefreshCommand({
+      installer,
+      bunExecutable: process.argv[0] || "bun",
+      pantryExecutable: resolvePantryExecutable(pantryExecutableCandidates(projectRoot), existsSync)
+    });
+    console.log(`Running \`${installer} install\` to refresh dependencies...`);
     try {
       await runPostSyncDependencyRefresh({
-        bunExecutable: process.argv[0] || "bun",
+        cmd,
         projectRoot,
         spawn: (spawnOptions) => Bun.spawn(spawnOptions)
       });
     } catch (err) {
-      console.warn(`  bun install failed (non-fatal): ${err?.message || err}`);
+      console.warn(`  ${installer} install failed (non-fatal): ${err?.message || err}`);
     }
   }
   const migrationsDir = join(projectRoot, "database", "migrations");
@@ -445,6 +486,14 @@ async function runPostSyncHooks(args) {
     });
   }
 }
+function pantryExecutableCandidates(projectRoot) {
+  const home = process.env.HOME ?? "";
+  return [
+    join(projectRoot, "pantry", ".bin", "pantry"),
+    home ? join(home, ".local", "bin", "pantry") : "",
+    home ? join(home, ".local", "share", "pantry", "global", "bin", "pantry") : ""
+  ].filter(Boolean);
+}
 function pkgJsonInTree(dir) {
   try {
     if (!existsSync(dir))

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/actions",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.162",
+  "version": "0.70.164",
   "description": "The Stacks actions.",
   "author": "Chris Breuer",
   "contributors": [
@@ -62,32 +62,32 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/config": "0.70.162",
+    "@stacksjs/config": "0.70.164",
     "@stacksjs/bumpx": "^0.2.6",
     "@stacksjs/bunpress": "^0.1.18",
     "@stacksjs/logsmith": "^0.2.3",
-    "@stacksjs/registry": "0.70.162",
-    "@stacksjs/ts-cloud": "^0.7.56",
+    "@stacksjs/registry": "0.70.164",
+    "@stacksjs/ts-cloud": "^0.7.60",
     "@stacksjs/ts-md": "^0.1.1"
   },
   "devDependencies": {
-    "@stacksjs/api": "0.70.162",
-    "@stacksjs/cli": "0.70.162",
-    "@stacksjs/config": "0.70.162",
-    "@stacksjs/database": "0.70.162",
+    "@stacksjs/api": "0.70.164",
+    "@stacksjs/cli": "0.70.164",
+    "@stacksjs/config": "0.70.164",
+    "@stacksjs/database": "0.70.164",
     "@stacksjs/tlsx": "^0.13.2",
     "better-dx": "^0.2.17",
-    "@stacksjs/dns": "0.70.162",
-    "@stacksjs/enums": "0.70.162",
-    "@stacksjs/env": "0.70.162",
-    "@stacksjs/error-handling": "0.70.162",
-    "@stacksjs/logging": "0.70.162",
-    "@stacksjs/path": "0.70.162",
-    "@stacksjs/security": "0.70.162",
-    "@stacksjs/storage": "0.70.162",
-    "@stacksjs/strings": "0.70.162",
-    "@stacksjs/utils": "0.70.162",
-    "@stacksjs/validation": "0.70.162"
+    "@stacksjs/dns": "0.70.164",
+    "@stacksjs/enums": "0.70.164",
+    "@stacksjs/env": "0.70.164",
+    "@stacksjs/error-handling": "0.70.164",
+    "@stacksjs/logging": "0.70.164",
+    "@stacksjs/path": "0.70.164",
+    "@stacksjs/security": "0.70.164",
+    "@stacksjs/storage": "0.70.164",
+    "@stacksjs/strings": "0.70.164",
+    "@stacksjs/utils": "0.70.164",
+    "@stacksjs/validation": "0.70.164"
   },
   "peerDependencies": {
     "pickier": "^0.1.35"