@stacksjs/path 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)
 
 ## 🙏🏼 Credits
 

package/dist/index.d.ts

@@ -807,6 +807,16 @@ export declare function scriptsPath(path?: string): string;
  * @returns The absolute path to the specified file or directory within the scheduler directory.
  */
 export declare function schedulerPath(path?: string): string;
+/**
+ * Returns the path to the `skills` directory within the core directory.
+ *
+ * That is the `@stacksjs/skills` package. The skills it reads ship from
+ * `storage/framework/defaults/ai/skills`, not from here.
+ *
+ * @param path - The relative path to the file or directory within the skills directory.
+ * @returns The absolute path to the specified file or directory within the skills directory.
+ */
+export declare function skillsPath(path?: string): string;
 /**
  * Returns the path to the `slug` directory within the core directory.
  *
@@ -929,6 +939,108 @@ export declare function utilsPath(path?: string): string;
  * @returns The absolute path to the specified file or directory within the validation directory.
  */
 export declare function validationPath(path?: string): string;
+/**
+ * Returns the path to the framework's runtime scratch directory.
+ *
+ * This is where the framework keeps short-lived, machine-local state that is
+ * neither source nor build output: the `buddy migrate` lockfile, the marker a
+ * migration subprocess writes back to the CLI, temporary bundles, and similar.
+ * Nothing in here is committed, and deleting the whole directory is always safe.
+ *
+ * It used to live at `./.stacks` in the project root. Everything runtime-owned
+ * now sits under `storage/` so the root only holds files you author.
+ *
+ * @param path - The relative path to the file or directory within the runtime directory.
+ * @returns The absolute path to the specified file or directory.
+ * @example
+ * ```ts
+ * import { frameworkRuntimePath } from '@stacksjs/path'
+ *
+ * console.log(frameworkRuntimePath('migrations.lock'))
+ * ```
+ */
+export declare function frameworkRuntimePath(path?: string): string;
+/**
+ * Returns the path to stx's build cache and generated route manifest.
+ *
+ * stx writes its compiled-template cache, Crosswind CSS cache, client-script
+ * bundles and `routes.ts` manifest here. It used to be `./.stx` in the project
+ * root; stx now takes the location from its own `stateDir` config option, which
+ * `config/ui.ts` sets to this directory and {@link runtimeDirectoryEnv} exports
+ * as `STX_DIR` for every process the project starts.
+ *
+ * @param path - The relative path to the file or directory within the stx cache.
+ * @returns The absolute path to the specified file or directory.
+ */
+export declare function stxPath(path?: string): string;
+/**
+ * Returns the path to the local cloud state directory.
+ *
+ * ts-cloud persists per-environment driver state, cached templates, and the
+ * management dashboard's credentials here. These are machine-local secrets and
+ * caches, never committed. It used to be `./.ts-cloud` in the project root;
+ * ts-cloud now takes the location from its own `stateDir` config option, which
+ * `config/cloud.ts` sets to this directory and {@link runtimeDirectoryEnv}
+ * exports as `TS_CLOUD_STATE_DIR` for every process the project starts.
+ *
+ * Not to be confused with {@link cloudPath}, which points at the committed
+ * `cloud/` infrastructure-as-code directory.
+ *
+ * @param path - The relative path to the file or directory within the cloud state directory.
+ * @returns The absolute path to the specified file or directory.
+ */
+export declare function cloudStatePath(path?: string): string;
+/**
+ * The environment stx and ts-cloud need in order to find their state.
+ *
+ * Both take the directory from their own config (`config/ui.ts` sets stx's
+ * `stateDir`, `config/cloud.ts` sets ts-cloud's), but a config is only read
+ * once something loads it, and both libraries reach for their state from module
+ * scope and from helpers that never see a config object. Their documented
+ * override is an environment variable, which is also what carries the answer
+ * into every process a command spawns. Absolute, so a code path resolving
+ * against a subdirectory still lands in the same place.
+ */
+export declare function runtimeDirectoryEnv(): Record<string, string>;
+/**
+ * Applies {@link runtimeDirectoryEnv} to `process.env`.
+ *
+ * An explicitly set value wins: someone who exports `STX_DIR` before running a
+ * command means it.
+ */
+export declare function applyRuntimeDirectoryEnv(): void;
+/**
+ * Recursively merges `from` into `to`, keeping whatever is already at `to`.
+ *
+ * The recursion matters: a shallow "rename each top-level entry unless it
+ * exists" pass would delete an entire subtree just because a sibling file
+ * inside it happened to be present at the destination. Directories present on
+ * both sides are merged entry by entry; only files that already exist at the
+ * destination are dropped from the source.
+ */
+export declare function mergeDirectoryInto(from: string, to: string): void;
+/**
+ * Creates the framework's runtime directories under `storage/` and clears the
+ * legacy root-level entries.
+ *
+ * For each relocated directory this:
+ *
+ *  1. creates the target under `storage/` if it does not exist yet,
+ *  2. recursively merges a pre-existing real directory in the project root into
+ *     it (anything already at the target wins, so re-running is safe),
+ *  3. removes what is left in the root - including the symlink earlier versions
+ *     put there, now that stx and ts-cloud are configured to read the target
+ *     directly.
+ *
+ * A symlink pointing anywhere other than the target is left alone: it is not
+ * ours to remove (an old checkout's `.stacks` may still be the core-source
+ * shortcut that `buddy generate:core-symlink` now writes to `.framework`).
+ *
+ * Every step is best-effort - this must never throw or block a command.
+ *
+ * @returns What is now in place for each relocated directory.
+ */
+export declare function ensureRuntimeDirectories(): RuntimeDirectoryState[];
 /**
  * Returns the path to the `validation` directory within the core directory.
  *
@@ -944,6 +1056,18 @@ export declare function socialsPath(path?: string): string;
  */
 export declare function homeDir(path?: string): string;
 export declare const path: Path;
+/**
+ * The outcome of relocating one runtime directory.
+ *
+ * `cleared` says whether the old root-level entry is gone. It stays false only
+ * when something we should not touch is sitting there - a symlink someone else
+ * created, or an entry we could not remove.
+ */
+export declare interface RuntimeDirectoryState {
+  legacy: string
+  target: string
+  cleared: boolean
+}
 export declare interface Path {
   actionsPath: (path?: string) => string
   userActionsPath: (path?: string) => string
@@ -971,7 +1095,13 @@ export declare interface Path {
   chatPath: (path?: string) => string
   cliPath: (path?: string) => string
   cloudPath: (path?: string) => string
+  cloudStatePath: (path?: string) => string
   frameworkCloudPath: (path?: string) => string
+  frameworkRuntimePath: (path?: string) => string
+  stxPath: (path?: string) => string
+  ensureRuntimeDirectories: () => RuntimeDirectoryState[]
+  runtimeDirectoryEnv: () => Record<string, string>
+  applyRuntimeDirectoryEnv: () => void
   collectionsPath: (path?: string) => string
   commandsPath: (path?: string) => string
   componentsPath: (path?: string) => string
@@ -1037,6 +1167,7 @@ export declare interface Path {
   schedulerPath: (path?: string) => string
   settingsPath: (path?: string) => string
   smsPath: (path?: string) => string
+  skillsPath: (path?: string) => string
   slugPath: (path?: string) => string
   scriptsPath: (path?: string) => string
   securityPath: (path?: string) => string

package/dist/index.js

@@ -1,6 +1,15 @@
 // @bun
 // src/index.ts
-import { existsSync } from "fs";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  unlinkSync
+} from "fs";
 import os from "os";
 import {
   basename,
@@ -387,6 +396,9 @@ function scriptsPath(path) {
 function schedulerPath(path) {
   return corePath(`scheduler/${path || ""}`);
 }
+function skillsPath(path) {
+  return corePath(`skills/${path || ""}`);
+}
 function slugPath(path) {
   return corePath(`slug/${path || ""}`);
 }
@@ -450,6 +462,81 @@ function utilsPath(path) {
 function validationPath(path) {
   return corePath(`validation/${path || ""}`);
 }
+function frameworkRuntimePath(path) {
+  return frameworkPath(`runtime/${path || ""}`);
+}
+function stxPath(path) {
+  return frameworkPath(`stx/${path || ""}`);
+}
+function cloudStatePath(path) {
+  return storagePath(`cloud/${path || ""}`);
+}
+var RELOCATED_RUNTIME_DIRECTORIES = [
+  { legacy: ".stx", target: stxPath },
+  { legacy: ".ts-cloud", target: cloudStatePath },
+  { legacy: ".stacks", target: frameworkRuntimePath }
+];
+function runtimeDirectoryEnv() {
+  return {
+    STX_DIR: stxPath().replace(/\/$/, ""),
+    TS_CLOUD_STATE_DIR: cloudStatePath().replace(/\/$/, "")
+  };
+}
+function applyRuntimeDirectoryEnv() {
+  for (const [key, value] of Object.entries(runtimeDirectoryEnv())) {
+    if (!process.env[key]?.trim())
+      process.env[key] = value;
+  }
+}
+function mergeDirectoryInto(from, to) {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    const source = join(from, entry);
+    const destination = join(to, entry);
+    if (!existsSync(destination)) {
+      renameSync(source, destination);
+      continue;
+    }
+    if (lstatSync(source).isDirectory() && lstatSync(destination).isDirectory()) {
+      mergeDirectoryInto(source, destination);
+      rmSync(source, { recursive: true, force: true });
+      continue;
+    }
+    rmSync(source, { recursive: true, force: true });
+  }
+}
+function ensureRuntimeDirectories() {
+  const results = [];
+  for (const { legacy, target } of RELOCATED_RUNTIME_DIRECTORIES) {
+    const legacyPath = projectPath(legacy);
+    const targetPath = target();
+    try {
+      mkdirSync(targetPath, { recursive: true });
+      const stats = lstatSync(legacyPath, { throwIfNoEntry: false });
+      if (!stats) {
+        results.push({ legacy: legacyPath, target: targetPath, cleared: true });
+        continue;
+      }
+      if (stats.isSymbolicLink()) {
+        const pointsAtTarget = resolve(dirname(legacyPath), readlinkSync(legacyPath)) === resolve(targetPath);
+        if (!pointsAtTarget) {
+          results.push({ legacy: legacyPath, target: targetPath, cleared: false });
+          continue;
+        }
+        unlinkSync(legacyPath);
+      } else if (stats.isDirectory()) {
+        mergeDirectoryInto(legacyPath, targetPath);
+        rmSync(legacyPath, { recursive: true, force: true });
+      } else {
+        rmSync(legacyPath, { force: true });
+      }
+      results.push({ legacy: legacyPath, target: targetPath, cleared: true });
+    } catch {
+      results.push({ legacy: legacyPath, target: targetPath, cleared: false });
+    }
+  }
+  return results;
+}
 function socialsPath(path) {
   return corePath(`socials/${path || ""}`);
 }
@@ -483,6 +570,12 @@ var path = {
   chatPath,
   cliPath,
   cloudPath,
+  cloudStatePath,
+  frameworkRuntimePath,
+  stxPath,
+  ensureRuntimeDirectories,
+  runtimeDirectoryEnv,
+  applyRuntimeDirectoryEnv,
   frameworkCloudPath,
   collectionsPath,
   commandsPath,
@@ -549,6 +642,7 @@ var path = {
   schedulerPath,
   settingsPath,
   smsPath,
+  skillsPath,
   slugPath,
   scriptsPath,
   securityPath,
@@ -621,6 +715,7 @@ export {
   tinkerPath,
   testsPath,
   testingPath,
+  stxPath,
   stringsPath,
   storesPath,
   storagePath,
@@ -630,6 +725,7 @@ export {
   socialsPath,
   smsPath,
   slugPath,
+  skillsPath,
   shellPath,
   settingsPath,
   serverlessPath,
@@ -640,6 +736,7 @@ export {
   scriptsPath,
   schedulerPath,
   runtimePath,
+  runtimeDirectoryEnv,
   routesPath,
   routerPath,
   resourcesPath,
@@ -667,6 +764,7 @@ export {
   newsletterPath,
   modulesPath,
   modelsPath,
+  mergeDirectoryInto,
   logsPath,
   loggingPath,
   listenersPath,
@@ -683,6 +781,7 @@ export {
   healthPath,
   gitPath,
   functionsPath,
+  frameworkRuntimePath,
   frameworkPath,
   frameworkCloudPath,
   findProjectPath,
@@ -694,6 +793,7 @@ export {
   eslintPluginPath,
   errorHandlingPath,
   enumsPath,
+  ensureRuntimeDirectories,
   emailPath,
   docsPath,
   dnsPath,
@@ -714,6 +814,7 @@ export {
   componentsPath,
   commandsPath,
   collectionsPath,
+  cloudStatePath,
   cloudPath,
   cliPath,
   chatPath,
@@ -728,6 +829,7 @@ export {
   authPath,
   assetsPath,
   arraysPath,
+  applyRuntimeDirectoryEnv,
   appPath,
   analyticsPath,
   aliasPath,

package/package.json

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