@ts-cloud/core 0.7.59 → 0.7.61

package/dist/index.d.ts

@@ -2,6 +2,7 @@
  * ts-cloud Core - CloudFormation Generator Engine
  */
 export * from './types';
+export * from './state-dir';
 export * from './deployment-mode';
 export * from './app-database';
 export * from './drivers';

package/dist/index.js

@@ -1017,6 +1017,34 @@ var RealtimePresets = {
     }
   }
 };
+// src/state-dir.ts
+import { isAbsolute, join, relative } from "node:path";
+var DEFAULT_STATE_DIR = ".ts-cloud";
+var STATE_DIR_ENV_VAR = "TS_CLOUD_STATE_DIR";
+var configuredStateDir = null;
+function setStateDir(dir) {
+  const trimmed = dir?.trim();
+  configuredStateDir = trimmed || null;
+}
+function stateDir() {
+  const fromEnv = process.env[STATE_DIR_ENV_VAR]?.trim();
+  return fromEnv || configuredStateDir || DEFAULT_STATE_DIR;
+}
+function statePath(...segments) {
+  return join(stateDir(), ...segments);
+}
+function resolveStatePath(cwd, ...segments) {
+  const dir = stateDir();
+  return isAbsolute(dir) ? join(dir, ...segments) : join(cwd, dir, ...segments);
+}
+function isStatePath(path, root = process.cwd()) {
+  const inside = (parent, child) => {
+    const rel = relative(parent, child);
+    return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+  };
+  const absolute = isAbsolute(path) ? path : join(root, path);
+  return inside(resolveStatePath(root), absolute);
+}
 // src/deployment-mode.ts
 function detectDeploymentTargets(config) {
   const server = config.infrastructure?.compute != null;
@@ -1985,7 +2013,7 @@ function formatDiff(diff) {
 }
 // src/modules/storage.ts
 import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join as join2 } from "node:path";
 class Storage {
   static createBucket(options) {
     const {
@@ -2544,11 +2572,11 @@ class Storage {
   static docsExist(options = {}) {
     const { projectRoot = process.cwd(), docsPaths = ["docs", "documentation", "doc"] } = options;
     for (const docsPath of docsPaths) {
-      const fullPath = join(projectRoot, docsPath);
+      const fullPath = join2(projectRoot, docsPath);
       if (existsSync(fullPath)) {
         const distPaths = ["dist", "build", ".bunpress/dist", "_site", "out", "public"];
         for (const distPath of distPaths) {
-          const fullDistPath = join(fullPath, distPath);
+          const fullDistPath = join2(fullPath, distPath);
           if (existsSync(fullDistPath)) {
             try {
               const files = readdirSync(fullDistPath);
@@ -2663,16 +2691,16 @@ class Storage {
     const privatePath = paths.private || "private";
     return {
       web: {
-        exists: existsSync(join(projectRoot, webPath)),
-        path: join(projectRoot, webPath)
+        exists: existsSync(join2(projectRoot, webPath)),
+        path: join2(projectRoot, webPath)
       },
       docs: {
-        exists: existsSync(join(projectRoot, docsPath)),
-        path: join(projectRoot, docsPath)
+        exists: existsSync(join2(projectRoot, docsPath)),
+        path: join2(projectRoot, docsPath)
       },
       private: {
-        exists: existsSync(join(projectRoot, privatePath)),
-        path: join(projectRoot, privatePath)
+        exists: existsSync(join2(projectRoot, privatePath)),
+        path: join2(projectRoot, privatePath)
       }
     };
   }
@@ -14840,7 +14868,7 @@ class Auth {
 // src/modules/deployment.ts
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync as existsSync2, readdirSync as readdirSync2, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join as join2 } from "node:path";
+import { basename, dirname, extname, join as join3 } from "node:path";
 class Deployment {
   static createApplication(options) {
     const { slug, environment, applicationName, computePlatform } = options;
@@ -15202,7 +15230,7 @@ class AssetHasher {
     if (dir === ".") {
       return `${name}.${hash}${ext}`;
     }
-    return join2(dir, `${name}.${hash}${ext}`);
+    return join3(dir, `${name}.${hash}${ext}`);
   }
   static collectFiles(directory, relativeTo) {
     const files = [];
@@ -15212,7 +15240,7 @@ class AssetHasher {
     }
     const entries = readdirSync2(directory, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join2(directory, entry.name);
+      const fullPath = join3(directory, entry.name);
       if (entry.isDirectory()) {
         files.push(...AssetHasher.collectFiles(fullPath, baseDir));
       } else if (entry.isFile()) {
@@ -15242,7 +15270,7 @@ class AssetHasher {
       assets.push(asset);
       hashMap[relativePath] = hashedRelativePath;
       if (outputDir) {
-        const destPath = join2(outputDir, hashedRelativePath);
+        const destPath = join3(outputDir, hashedRelativePath);
         const destDir = dirname(destPath);
         if (!existsSync2(destDir)) {
           const { mkdirSync } = __require("node:fs");
@@ -15260,7 +15288,7 @@ class AssetHasher {
       hashMap
     };
     if (outputDir) {
-      const manifestPath = join2(outputDir, "asset-manifest.json");
+      const manifestPath = join3(outputDir, "asset-manifest.json");
       writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
     }
     return manifest;
@@ -15355,7 +15383,7 @@ class AssetHasher {
         cc = cacheControl.hashed || "public, max-age=31536000, immutable";
       }
       return {
-        localPath: join2(sourceDir, asset.originalPath),
+        localPath: join3(sourceDir, asset.originalPath),
         s3Key: keyPrefix ? `${keyPrefix}/${asset.hashedPath}` : asset.hashedPath,
         contentType: asset.contentType,
         cacheControl: cc,
@@ -22303,7 +22331,7 @@ function createDashboardSite(options) {
   };
 }
 // src/presets/management-dashboard.ts
-var DASHBOARD_STATE_DIR = ".ts-cloud";
+var DASHBOARD_STATE_DIR = DEFAULT_STATE_DIR;
 var DASHBOARD_ENTRY = "./node_modules/@stacksjs/ts-cloud/dist/bin/cli.js";
 function apexOf(domain) {
   const parts = domain.split(".").filter(Boolean);
@@ -22492,7 +22520,7 @@ init_signature();
 // src/aws/credentials.ts
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "node:fs";
 import { homedir } from "node:os";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 function fromEnvironment() {
   const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
   const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
@@ -22507,7 +22535,7 @@ function fromEnvironment() {
 }
 function fromSharedCredentials(options) {
   const profile = options?.profile || process.env.AWS_PROFILE || "default";
-  const credentialsPath = options?.credentialsFile || join3(homedir(), ".aws", "credentials");
+  const credentialsPath = options?.credentialsFile || join4(homedir(), ".aws", "credentials");
   if (!existsSync3(credentialsPath)) {
     return null;
   }
@@ -22744,7 +22772,7 @@ function resolveRegion(profile) {
   if (envRegion) {
     return envRegion;
   }
-  const configPath = join3(homedir(), ".aws", "config");
+  const configPath = join4(homedir(), ".aws", "config");
   if (existsSync3(configPath)) {
     try {
       const content = readFileSync2(configPath, "utf-8");
@@ -24635,20 +24663,21 @@ function suggestQuotaIncrease(quotas) {
 // src/utils/cache.ts
 import { createHash as createHash2 } from "node:crypto";
 import { existsSync as existsSync4, mkdirSync, readdirSync as readdirSync3, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 class FileCache {
   cacheDir;
   ttl;
   constructor(cacheDir, options = {}) {
     this.cacheDir = cacheDir;
     this.ttl = options.ttl || 24 * 60 * 60 * 1000;
-    if (!existsSync4(cacheDir)) {
-      mkdirSync(cacheDir, { recursive: true });
-    }
+  }
+  ensureCacheDir() {
+    if (!existsSync4(this.cacheDir))
+      mkdirSync(this.cacheDir, { recursive: true });
   }
   getCachePath(key) {
     const hash2 = createHash2("sha256").update(key).digest("hex");
-    return join4(this.cacheDir, `${hash2}.json`);
+    return join5(this.cacheDir, `${hash2}.json`);
   }
   get(key) {
     const cachePath = this.getCachePath(key);
@@ -24669,6 +24698,7 @@ class FileCache {
     }
   }
   set(key, value, hash2) {
+    this.ensureCacheDir();
     const cachePath = this.getCachePath(key);
     const entry = {
       value,
@@ -24681,16 +24711,20 @@ class FileCache {
     return this.get(key) !== undefined;
   }
   clear() {
+    if (!existsSync4(this.cacheDir))
+      return;
     const files = readdirSync3(this.cacheDir);
     for (const file of files) {
-      unlinkSync(join4(this.cacheDir, file));
+      unlinkSync(join5(this.cacheDir, file));
     }
   }
   prune() {
+    if (!existsSync4(this.cacheDir))
+      return;
     const files = readdirSync3(this.cacheDir);
     const now = Date.now();
     for (const file of files) {
-      const filePath = join4(this.cacheDir, file);
+      const filePath = join5(this.cacheDir, file);
       try {
         const data = readFileSync3(filePath, "utf-8");
         const entry = JSON.parse(data);
@@ -24706,7 +24740,7 @@ class FileCache {
 
 class TemplateCache {
   cache;
-  constructor(cacheDir = ".ts-cloud/cache/templates") {
+  constructor(cacheDir = statePath("cache", "templates")) {
     this.cache = new FileCache(cacheDir, {
       ttl: 24 * 60 * 60 * 1000
     });
@@ -24737,11 +24771,16 @@ class TemplateCache {
     this.cache.prune();
   }
 }
-var templateCache = new TemplateCache;
+var sharedTemplateCache = null;
+function templateCache() {
+  if (!sharedTemplateCache)
+    sharedTemplateCache = new TemplateCache;
+  return sharedTemplateCache;
+}
 // src/utils/hash.ts
 import { createHash as createHash3 } from "node:crypto";
 import { createReadStream, readdirSync as readdirSync4, statSync as statSync2 } from "node:fs";
-import { join as join5, relative } from "node:path";
+import { join as join6, relative as relative2 } from "node:path";
 async function hashFile(filePath, options = {}) {
   const algorithm = options.algorithm || "sha256";
   const chunkSize = options.chunkSize || 64 * 1024;
@@ -24760,13 +24799,13 @@ function hashBuffer(buffer, algorithm = "sha256") {
   return createHash3(algorithm).update(buffer).digest("hex");
 }
 async function hashDirectory(dirPath, options = {}) {
-  const ignorePatterns = options.ignorePatterns || ["node_modules", ".git", "dist", "build", ".ts-cloud"];
+  const ignorePatterns = options.ignorePatterns || ["node_modules", ".git", "dist", "build", stateDir()];
   const files = [];
   async function walk(dir) {
     const entries = readdirSync4(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join5(dir, entry.name);
-      const relativePath = relative(dirPath, fullPath);
+      const fullPath = join6(dir, entry.name);
+      const relativePath = relative2(dirPath, fullPath);
       if (ignorePatterns.some((pattern) => relativePath.includes(pattern))) {
         continue;
       }
@@ -45332,10 +45371,10 @@ import { execSync } from "node:child_process";
 import { createHash as createHash4 } from "node:crypto";
 import { cpSync, mkdtempSync, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname as dirname2, isAbsolute, join as join6, resolve } from "node:path";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join7, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 function adapterSourcePath() {
-  return join6(dirname2(fileURLToPath(import.meta.url)), "runtime", "adapter.ts");
+  return join7(dirname2(fileURLToPath(import.meta.url)), "runtime", "adapter.ts");
 }
 function runBuildHooks(hooks, cwd, onStep) {
   for (const hook of hooks ?? []) {
@@ -45357,11 +45396,11 @@ async function packageServerlessApp(opts) {
   const entry = app.entry;
   if (!entry)
     throw new Error("serverless app: `entry` is required to package a Node/Bun application");
-  const entryPath = isAbsolute(entry) ? entry : join6(projectRoot, entry);
-  const stage = mkdtempSync(join6(tmpdir(), "tscloud-pkg-"));
+  const entryPath = isAbsolute2(entry) ? entry : join7(projectRoot, entry);
+  const stage = mkdtempSync(join7(tmpdir(), "tscloud-pkg-"));
   try {
-    cpSync(adapterSourcePath(), join6(stage, "adapter.ts"));
-    const bootstrapPath = join6(stage, "bootstrap.ts");
+    cpSync(adapterSourcePath(), join7(stage, "adapter.ts"));
+    const bootstrapPath = join7(stage, "bootstrap.ts");
     writeFileSync3(bootstrapPath, generateBootstrap({ entryImport: entryPath, adapterImport: "./adapter" }));
     opts.onStep?.("bundling application");
     const result = await Bun.build({
@@ -46353,33 +46392,33 @@ CMD [ "index.http" ]
 import { execFileSync } from "node:child_process";
 import { mkdtempSync as mkdtempSync2, readFileSync as readFileSync4, rmSync as rmSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
-import { dirname as dirname3, join as join7 } from "node:path";
+import { dirname as dirname3, join as join8 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function assetsDir() {
   return dirname3(fileURLToPath2(import.meta.url));
 }
 function sharedRuntimeLoop() {
-  return readFileSync4(join7(assetsDir(), "runtime.mjs"), "utf-8");
+  return readFileSync4(join8(assetsDir(), "runtime.mjs"), "utf-8");
 }
 function bootstrap(kind) {
-  return readFileSync4(join7(assetsDir(), `${kind}-bootstrap`), "utf-8");
+  return readFileSync4(join8(assetsDir(), `${kind}-bootstrap`), "utf-8");
 }
 function buildNodeRuntimeLayerZip(options) {
   const architecture = options.architecture ?? "x86_64";
   const nodeArch = architecture === "arm64" ? "arm64" : "x64";
   const version = options.version.replace(/^v/, "");
   const step = options.onStep ?? (() => {});
-  const stage = mkdtempSync2(join7(tmpdir2(), "tscloud-node-layer-"));
+  const stage = mkdtempSync2(join8(tmpdir2(), "tscloud-node-layer-"));
   try {
     const exact = version.includes(".") ? version : resolveLatestNode(version);
     const dir = `node-v${exact}-linux-${nodeArch}`;
     const url = `https://nodejs.org/dist/v${exact}/${dir}.tar.xz`;
     step(`downloading Node ${exact} (${architecture})`);
-    const tar = join7(stage, "node.tar.xz");
+    const tar = join8(stage, "node.tar.xz");
     fetchToFile(url, tar);
     step("extracting node binary");
     execFileSync("tar", ["-xf", tar, "-C", stage, `${dir}/bin/node`], { stdio: "inherit" });
-    const nodeBin = readFileSync4(join7(stage, dir, "bin", "node"));
+    const nodeBin = readFileSync4(join8(stage, dir, "bin", "node"));
     step("packaging layer");
     const entries = [
       { name: "bootstrap", data: bootstrap("node"), mode: 493 },
@@ -46396,15 +46435,15 @@ function buildBunRuntimeLayerZip(options) {
   const bunArch = architecture === "arm64" ? "bun-linux-aarch64" : "bun-linux-x64";
   const version = options.version === "latest" ? "" : options.version.replace(/^v/, "");
   const step = options.onStep ?? (() => {});
-  const stage = mkdtempSync2(join7(tmpdir2(), "tscloud-bun-layer-"));
+  const stage = mkdtempSync2(join8(tmpdir2(), "tscloud-bun-layer-"));
   try {
     const url = version ? `https://github.com/oven-sh/bun/releases/download/bun-v${version}/${bunArch}.zip` : `https://github.com/oven-sh/bun/releases/latest/download/${bunArch}.zip`;
     step(`downloading Bun ${version || "latest"} (${architecture})`);
-    const zipPath = join7(stage, "bun.zip");
+    const zipPath = join8(stage, "bun.zip");
     fetchToFile(url, zipPath);
     step("extracting bun binary");
     execFileSync("unzip", ["-o", "-q", zipPath, "-d", stage], { stdio: "inherit" });
-    const bunBin = readFileSync4(join7(stage, bunArch, "bun"));
+    const bunBin = readFileSync4(join8(stage, bunArch, "bun"));
     step("packaging layer");
     const entries = [
       { name: "bootstrap", data: bootstrap("bun"), mode: 493 },
@@ -46589,14 +46628,14 @@ clear_env = no
 }
 // src/serverless-php/runtime-assets.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname4, join as join8 } from "node:path";
+import { dirname as dirname4, join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 function assetsDir2() {
-  return join8(dirname4(fileURLToPath3(import.meta.url)), "runtime-assets");
+  return join9(dirname4(fileURLToPath3(import.meta.url)), "runtime-assets");
 }
 function phpRuntimeLayerAssets() {
   const dir = assetsDir2();
-  const read = (f) => readFileSync5(join8(dir, f), "utf-8");
+  const read = (f) => readFileSync5(join9(dir, f), "utf-8");
   return [
     { path: "bootstrap", contents: read("bootstrap"), mode: 493 },
     { path: "tscloud/runtime.php", contents: read("runtime.php"), mode: 420 },
@@ -46635,10 +46674,10 @@ var LARAVEL_SERVERLESS_BUILD_STEPS = [
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync5, mkdirSync as mkdirSync2, mkdtempSync as mkdtempSync3, readdirSync as readdirSync5, readFileSync as readFileSync6, rmSync as rmSync3, statSync as statSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
-import { join as join9, relative as relative2 } from "node:path";
+import { join as join10, relative as relative3 } from "node:path";
 function* walk(dir) {
   for (const entry of readdirSync5(dir)) {
-    const full = join9(dir, entry);
+    const full = join10(dir, entry);
     if (statSync3(full).isDirectory())
       yield* walk(full);
     else
@@ -46649,26 +46688,26 @@ function buildPhpRuntimeLayerZip(options = {}) {
   const architecture = options.architecture ?? "x86_64";
   const platform = options.platform ?? (architecture === "arm64" ? "linux/arm64" : "linux/amd64");
   const step = options.onStep ?? (() => {});
-  const stage = mkdtempSync3(join9(tmpdir3(), "tscloud-php-layer-"));
+  const stage = mkdtempSync3(join10(tmpdir3(), "tscloud-php-layer-"));
   const imageTag = "tscloud-php-layer:build";
   try {
-    writeFileSync4(join9(stage, "Dockerfile"), generatePhpLayerDockerfile(options));
+    writeFileSync4(join10(stage, "Dockerfile"), generatePhpLayerDockerfile(options));
     step("Building PHP runtime image (docker)");
     execFileSync2("docker", ["build", "--platform", platform, "-t", imageTag, stage], { stdio: "inherit" });
     step("Extracting /opt/php from image");
     const cid = execFileSync2("docker", ["create", "--platform", platform, imageTag], { encoding: "utf-8" }).trim();
-    const optDir = join9(stage, "opt");
+    const optDir = join10(stage, "opt");
     mkdirSync2(optDir, { recursive: true });
     try {
-      execFileSync2("docker", ["cp", `${cid}:/opt/php`, join9(optDir, "php")], { stdio: "inherit" });
+      execFileSync2("docker", ["cp", `${cid}:/opt/php`, join10(optDir, "php")], { stdio: "inherit" });
     } finally {
       execFileSync2("docker", ["rm", cid], { stdio: "ignore" });
     }
-    if (!existsSync5(join9(optDir, "php", "bin", "php")))
+    if (!existsSync5(join10(optDir, "php", "bin", "php")))
       throw new Error("layer build produced no /opt/php/bin/php");
     const entries = [];
     for (const file of walk(optDir)) {
-      const rel = relative2(optDir, file).replace(/\\/g, "/");
+      const rel = relative3(optDir, file).replace(/\\/g, "/");
       const mode = statSync3(file).mode & 73 ? 493 : 420;
       entries.push({ name: rel, data: readFileSync6(file), mode });
     }
@@ -46689,7 +46728,7 @@ function buildPhpRuntimeLayerZip(options = {}) {
 import { execSync as execSync2 } from "node:child_process";
 import { createHash as createHash5 } from "node:crypto";
 import { readdirSync as readdirSync6, readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
-import { join as join10, relative as relative3, resolve as resolve2 } from "node:path";
+import { join as join11, relative as relative4, resolve as resolve2 } from "node:path";
 var PHP_DEFAULT_EXCLUDES = [
   ".git",
   ".github",
@@ -46710,8 +46749,8 @@ function isExcluded(rel, excludes) {
 }
 function* walk2(dir, root, excludes) {
   for (const entry of readdirSync6(dir)) {
-    const full = join10(dir, entry);
-    const rel = relative3(root, full).replace(/\\/g, "/");
+    const full = join11(dir, entry);
+    const rel = relative4(root, full).replace(/\\/g, "/");
     if (isExcluded(rel, excludes))
       continue;
     if (statSync4(full).isDirectory())
@@ -46732,10 +46771,10 @@ function runPhpBuildHooks(opts) {
 }
 function collectPhpAppEntries(projectRoot, exclude = []) {
   const root = resolve2(projectRoot);
-  const excludes = [...PHP_DEFAULT_EXCLUDES, ...exclude];
+  const excludes = [...PHP_DEFAULT_EXCLUDES, stateDir(), ...exclude];
   const entries = [];
   for (const file of walk2(root, root, excludes)) {
-    const rel = relative3(root, file).replace(/\\/g, "/");
+    const rel = relative4(root, file).replace(/\\/g, "/");
     const executable = (statSync4(file).mode & 73) !== 0;
     entries.push({ name: rel, data: readFileSync7(file), mode: executable ? 493 : 420 });
   }
@@ -47226,11 +47265,14 @@ export {
   suggestCommand,
   storageAdvancedManager,
   staticSiteManager,
+  statePath,
+  stateDir,
   stackDependencyManager,
   signRequestAsync,
   signRequest,
   sharedRuntimeLoop,
   sha256,
+  setStateDir,
   serviceMeshManager,
   sequence,
   senderReputationManager,
@@ -47247,6 +47289,7 @@ export {
   responseToResult,
   resourceManagementManager,
   resolveStorageBucketName,
+  resolveStatePath,
   resolveSiteStackName,
   resolveSiteResourceName,
   resolveSiteBucketName,
@@ -47309,6 +47352,7 @@ export {
   lambdaConcurrencyManager,
   isWebCryptoAvailable,
   isValidRegion,
+  isStatePath,
   isNodeCryptoAvailable,
   isManagementDashboardSiteName,
   isLocalDevelopment,
@@ -47492,6 +47536,7 @@ export {
   SecretsManager,
   Secrets,
   Search,
+  STATE_DIR_ENV_VAR,
   SMS,
   S3Error,
   S3Client,
@@ -47574,6 +47619,7 @@ export {
   DNSSECManager,
   DNS,
   DLQMonitoringManager,
+  DEFAULT_STATE_DIR,
   DEFAULT_SERVICE_LIMITS,
   DASHBOARD_STATE_DIR,
   DASHBOARD_PORT_SPAN,

package/dist/presets/management-dashboard.d.ts

@@ -57,8 +57,16 @@ export interface ManagementDashboardOptions {
      */
     version?: string;
 }
-/** Where the live dashboard keeps its users, session key and cache. */
-export declare const DASHBOARD_STATE_DIR = ".ts-cloud";
+/**
+ * Where the live dashboard keeps its users, session key and cache ON THE BOX,
+ * relative to its release directory.
+ *
+ * Deliberately the literal default rather than {@link stateDir}: that one is
+ * about the operator's machine (a Stacks checkout points it at `storage/cloud`),
+ * while this is the path the deploy carries across releases via `sharedPaths`.
+ * The two must agree with each other, not with the local checkout.
+ */
+export declare const DASHBOARD_STATE_DIR: string;
 /**
  * The dashboard service's entry point inside its release dir. The CLI is
  * installed from npm by the release's `bun install`, so this path exists on the

package/dist/state-dir.d.ts

@@ -0,0 +1,44 @@
+/** The directory used when nothing configures one. */
+export declare const DEFAULT_STATE_DIR = ".ts-cloud";
+/** Environment variable that overrides both the config and the default. */
+export declare const STATE_DIR_ENV_VAR = "TS_CLOUD_STATE_DIR";
+/**
+ * Records the `stateDir` coming from `cloud.config.ts`.
+ *
+ * Called by the config loader. Passing a nullish or blank value clears it,
+ * which is what a config without `stateDir` should do — otherwise a stale value
+ * from a previously loaded config would leak into the next one (tests, and the
+ * dashboard server loading configs for several projects).
+ */
+export declare function setStateDir(dir?: string | null): void;
+/**
+ * The configured state directory, as written — relative or absolute.
+ */
+export declare function stateDir(): string;
+/**
+ * Joins segments onto the state directory without resolving it against a root.
+ *
+ * Use this for the exported "where does X live" helpers, whose value is a
+ * project-relative path that callers then resolve against their own `cwd`.
+ */
+export declare function statePath(...segments: string[]): string;
+/**
+ * Absolute path to a file or directory inside the state directory.
+ *
+ * An absolute {@link stateDir} wins over `cwd`, so a project can pin its state
+ * to a fixed location regardless of where a command is run from.
+ */
+export declare function resolveStatePath(cwd: string, ...segments: string[]): string;
+/**
+ * Whether `path` is the state directory or something inside it.
+ *
+ * Everything that walks a project to package, hash, or ship it has to skip the
+ * state directory: it holds the dashboard credentials and the session key, and
+ * a deploy artifact that carries them is a credential leak. A hardcoded
+ * `.ts-cloud` check stops being enough the moment the directory is configurable,
+ * so ask this instead of comparing names.
+ *
+ * `path` may be absolute or relative to `root` (the project root, defaulting to
+ * the working directory).
+ */
+export declare function isStatePath(path: string, root?: string): boolean;

package/dist/state-dir.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -155,6 +155,21 @@ export interface CloudConfig {
      * Tags applied to all resources
      */
     tags?: Record<string, string>;
+    /**
+     * Where ts-cloud keeps its machine-local state: dashboard credentials and
+     * session secret, the auth encryption key, the control-plane database, the
+     * staged dashboard release, cached templates, restore scratch space.
+     *
+     * Defaults to `.ts-cloud` in the project root. Point it at an existing home
+     * for runtime state to keep the root clean - a Stacks application sets
+     * `storage/cloud`. Relative paths resolve against the project root; absolute
+     * paths are used as-is. `TS_CLOUD_STATE_DIR` overrides this.
+     *
+     * Not to be confused with `storage/cloud/state/`, where the drivers record
+     * the provisioned box per stack - that one is meant to be committed so CI can
+     * find an existing server instead of provisioning a duplicate.
+     */
+    stateDir?: string;
 }
 export type CloudOptions = Partial<CloudConfig>;
 export interface ProjectConfig {

package/dist/utils/cache.d.ts

@@ -51,6 +51,15 @@ export declare class FileCache<T = any> {
     private cacheDir;
     private ttl;
     constructor(cacheDir: string, options?: CacheOptions);
+    /**
+     * Create the cache directory, on the first write rather than on construction.
+     *
+     * Constructing a cache must not touch the filesystem: these objects get built
+     * eagerly at import time, before anything has had a chance to configure where
+     * state lives, and a directory created then lands in the wrong place and
+     * sticks around empty.
+     */
+    private ensureCacheDir;
     /**
      * Get cache file path for key
      */
@@ -107,7 +116,4 @@ export declare class TemplateCache {
      */
     prune(): void;
 }
-/**
- * Global template cache instance
- */
-export declare const templateCache: TemplateCache;
+export declare function templateCache(): TemplateCache;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ts-cloud/core",
   "type": "module",
-  "version": "0.7.59",
+  "version": "0.7.61",
   "description": "Core CloudFormation generation library for ts-cloud",
   "author": "Chris Breuer <chris@stacksjs.com>",
   "license": "MIT",
@@ -31,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ts-cloud/aws-types": "0.7.59"
+    "@ts-cloud/aws-types": "0.7.61"
   },
   "devDependencies": {
     "typescript": "^7.0.2"