@stacksjs/path 0.70.362 → 0.70.365

package/dist/index.d.ts

@@ -719,6 +719,22 @@ export declare function storagePath(path?: string): string;
  * @returns The absolute path to the specified file or directory within the public directory.
  */
 export declare function publicPath(path?: string): string;
+/** Where `buddy upgrade` reads the managed scaffold from. */
+export declare function defaultsPackagePath(projectRoot?: string): string;
+/** Version of the installed `@stacksjs/defaults`, or null when absent. */
+export declare function installedDefaultsVersion(projectRoot?: string): string | null;
+/**
+ * Compare the vendored framework defaults against the installed package.
+ *
+ * `storage/framework/defaults` is the copy that executes, and `buddy upgrade`
+ * is the only thing that writes it. Bump `stacks` in package.json and run
+ * `bun install`, which is how anyone moves a dependency, and the package
+ * advances while the vendored tree stays put.
+ *
+ * Cheap by construction: two manifest reads and one marker read, so callers on
+ * a boot path can consult it freely.
+ */
+export declare function inspectDefaultsProvenance(projectRoot?: string): DefaultsSkew;
 /**
  * Returns the path to the `push` directory within the `notifications` directory.
  *
@@ -1055,7 +1071,23 @@ export declare function socialsPath(path?: string): string;
  * @returns The absolute path to the specified file or directory within the home directory.
  */
 export declare function homeDir(path?: string): string;
+/**
+ * Provenance stamp written next to the synced tree. `buddy upgrade` is the only
+ * thing that writes `storage/framework/defaults`, so this is the only record of
+ * which release the tree came from.
+ */
+export declare const DEFAULTS_SYNC_MARKER: '.stacks-sync.json';
 export declare const path: Path;
+export declare interface DefaultsSyncMarker {
+  version: string
+  syncedAt: string
+}
+export declare interface DefaultsSkew {
+  status: DefaultsProvenance
+  installed: string | null
+  vendored: string | null
+  syncedAt: string | null
+}
 /**
  * The outcome of relocating one runtime directory.
  *
@@ -1154,6 +1186,9 @@ export declare interface Path {
   findProjectPath: (project: string) => Promise<string>
   coreStoragePath: (path?: string) => string
   publicPath: (path?: string) => string
+  defaultsPackagePath: (projectRoot?: string) => string
+  installedDefaultsVersion: (projectRoot?: string) => string | null
+  inspectDefaultsProvenance: (projectRoot?: string) => DefaultsSkew
   pushPath: (path?: string) => string
   queryBuilderPath: (path?: string) => string
   queuePath: (path?: string) => string
@@ -1220,4 +1255,12 @@ export declare interface Path {
  * @returns The absolute path to the specified library entry file.
  */
 export type LibraryType = 'web-components' | 'functions';
+/**
+ * - `not-applicable` — nothing to compare: no vendored tree, no installed
+ *   package, or a framework checkout where the tree is the source rather than a
+ *   copy of it.
+ * - `unstamped` — the tree predates provenance stamping, so only a file
+ *   comparison can say whether it is current.
+ */
+export type DefaultsProvenance = 'not-applicable' | 'current' | 'stale' | 'unstamped';
 export { basename, delimiter, dirname, extname, isAbsolute, join, normalize, relative, resolve, sep, toNamespacedPath };

package/dist/index.js

@@ -4,8 +4,10 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readFileSync,
   readdirSync,
   readlinkSync,
+  realpathSync,
   renameSync,
   rmSync,
   unlinkSync
@@ -353,6 +355,59 @@ function storagePath(path) {
 function publicPath(path) {
   return projectPath(`public/${path || ""}`);
 }
+var DEFAULTS_SYNC_MARKER = ".stacks-sync.json";
+function notApplicable() {
+  return { status: "not-applicable", installed: null, vendored: null, syncedAt: null };
+}
+function defaultsPackagePath(projectRoot = projectPath()) {
+  return join(projectRoot, "node_modules/@stacksjs/defaults");
+}
+function manifestVersion(packageRoot) {
+  try {
+    const version = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"))?.version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+function installedDefaultsVersion(projectRoot = projectPath()) {
+  return manifestVersion(defaultsPackagePath(projectRoot));
+}
+function isInside(child, parent) {
+  const resolved = realpathSync(child);
+  return resolved === parent || resolved.startsWith(`${parent}${sep}`);
+}
+function inspectDefaultsProvenance(projectRoot = projectPath()) {
+  const targetDefaults = join(projectRoot, "storage/framework/defaults");
+  const packageRoot = defaultsPackagePath(projectRoot);
+  if (!existsSync(targetDefaults) || !existsSync(join(packageRoot, "package.json")))
+    return notApplicable();
+  if (existsSync(join(projectRoot, "storage/framework/core/buddy/package.json")))
+    return notApplicable();
+  try {
+    if (!isInside(packageRoot, join(realpathSync(projectRoot), "node_modules")))
+      return notApplicable();
+  } catch {
+    return notApplicable();
+  }
+  const installed = manifestVersion(packageRoot);
+  if (!installed)
+    return notApplicable();
+  let marker = null;
+  try {
+    const raw = JSON.parse(readFileSync(join(targetDefaults, DEFAULTS_SYNC_MARKER), "utf8"));
+    if (typeof raw?.version === "string")
+      marker = { version: raw.version, syncedAt: typeof raw.syncedAt === "string" ? raw.syncedAt : "" };
+  } catch {}
+  if (!marker)
+    return { status: "unstamped", installed, vendored: null, syncedAt: null };
+  return {
+    status: marker.version === installed ? "current" : "stale",
+    installed,
+    vendored: marker.version,
+    syncedAt: marker.syncedAt || null
+  };
+}
 function pushPath(path) {
   return notificationsPath(`push/${path || ""}`);
 }
@@ -629,6 +684,9 @@ var path = {
   findProjectPath,
   coreStoragePath,
   publicPath,
+  defaultsPackagePath,
+  installedDefaultsVersion,
+  inspectDefaultsProvenance,
   pushPath,
   queryBuilderPath,
   queuePath,
@@ -777,6 +835,8 @@ export {
   join,
   jobsPath,
   isAbsolute,
+  installedDefaultsVersion,
+  inspectDefaultsProvenance,
   homeDir,
   healthPath,
   gitPath,
@@ -802,6 +862,7 @@ export {
   desktopPath,
   delimiter,
   defaultsResourcesPath,
+  defaultsPackagePath,
   defaultsAppPath,
   datetimePath,
   databasePath,
@@ -834,5 +895,6 @@ export {
   analyticsPath,
   aliasPath,
   aiPath,
-  actionsPath
+  actionsPath,
+  DEFAULTS_SYNC_MARKER
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/path",
   "type": "module",
-  "version": "0.70.362",
+  "version": "0.70.365",
   "description": "The Stacks path.",
   "author": "Chris Breuer",
   "contributors": [