@wildo-ai/platform-config-lib 1.0.1

package/src/workspace-scope/workspace-scope.schemas.ts

@@ -0,0 +1,224 @@
+import { homedir, tmpdir } from 'os';
+import { dirname, join, relative, resolve } from 'path';
+import { resolveWorkspaceScope } from './workspace-scope-detector';
+
+/**
+ * Workspace scope detection types.
+ *
+ * Provides a hierarchical scope model for determining where a tool
+ * (CLI, companion, IDE extension) is being invoked from within the
+ * Wildo project structure.
+ *
+ * Scope hierarchy (most specific wins, each implies parent scopes):
+ *   UNINITIALIZED → GLOBAL → FRAMEWORK → PROJECT → SAAS_APP
+ *
+ * Detection is based on committed config files as scope anchors,
+ * NOT on generated dot-directories (.wildo-project, .wildo-saas).
+ */
+
+/**
+ * Hierarchical workspace scope.
+ *
+ * Numeric values are ordered so that higher = more specific.
+ * This enables `>=` comparisons for "at least this scope" checks
+ * (e.g., `scope >= WorkspaceScope.PROJECT` means PROJECT or SAAS_APP).
+ */
+export enum WorkspaceScope {
+  /** No global preferences file found and CWD is outside any project or framework */
+  UNINITIALIZED = 0,
+  /** Global preferences file exists but CWD is outside any project or framework */
+  GLOBAL = 1,
+  /** CWD is inside the Wildo framework repository (.wildo-framework/ found) */
+  FRAMEWORK = 2,
+  /** CWD is inside a project (wildo.project.config.ts found) but not in a specific app */
+  PROJECT = 3,
+  /** CWD is inside a SaaS application directory (wildo.saas.config.ts found) */
+  SAAS_APP = 4,
+}
+
+/**
+ * Result of workspace scope detection.
+ *
+ * All resolved paths are populated regardless of the final scope — a command
+ * in SAAS_APP scope can still access `projectRoot` and `frameworkRoot`.
+ */
+export interface WorkspaceScopeResult {
+  /** Most specific scope detected from CWD */
+  scope: WorkspaceScope;
+
+  /** Absolute path to `wildo.saas.config.ts`, if found */
+  saasConfigPath: string | null;
+  /** Directory containing `wildo.saas.config.ts` */
+  saasRoot: string | null;
+
+  /** Absolute path to `wildo.project.config.ts`, if found */
+  projectConfigPath: string | null;
+  /** Directory containing `wildo.project.config.ts` */
+  projectRoot: string | null;
+
+  /** Directory containing `.wildo-framework/`, if found */
+  frameworkRoot: string | null;
+
+  /** Absolute path to the global preferences file, if it exists */
+  globalPreferencesPath: string | null;
+}
+
+/**
+ * Canonical config file and directory names used for scope detection.
+ * Single source of truth — CLI and other tools should reference these
+ * instead of hardcoding file names.
+ */
+export const WORKSPACE_CONFIG_NAMES = {
+  PROJECT: 'wildo.project.config.ts',
+  SAAS: 'wildo.saas.config.ts',
+  PLATFORM: 'wildo.platform.config.ts',
+  FRAMEWORK_DIR: '.wildo-framework',
+  PROJECT_DIR: '.wildo-project',
+  SAAS_DIR: '.wildo-saas',
+  GLOBAL_DIR: '.wildo',
+  PREFERENCES_FILE: 'preferences.json',
+  /** Directory under the project root containing platform configs and per-env overrides */
+  PLATFORM_DIR: 'wildo-platform',
+  /** File name prefix for per-env sharing policy files (e.g., `wildo.sharing-policy.local.ts`) */
+  SHARING_POLICY_PREFIX: 'wildo.sharing-policy.',
+} as const;
+
+/**
+ * Runtime-owned zones for generated config-evaluation artifacts.
+ *
+ * These are semantic owners, not source locations. For example, a platform
+ * config stored in a sibling `platformPath` still belongs to the project zone
+ * and must emit artifacts under `.wildo-project/dist/...`, not beside the
+ * authored config file itself.
+ */
+export enum ConfigArtifactsZone {
+  FRAMEWORK = 'framework',
+  PLATFORM = 'platform',
+  PROJECT = 'project',
+  SAAS = 'saas',
+  TEMP = 'temp',
+}
+
+export interface ConfigArtifactsLocationOptions {
+  zone: ConfigArtifactsZone;
+  ownerRoot: string;
+}
+
+export function resolveGlobalWildoHomePath(userHome: string = homedir()): string {
+  return join(userHome, WORKSPACE_CONFIG_NAMES.GLOBAL_DIR);
+}
+
+export function resolveGlobalPreferencesPath(userHome: string = homedir()): string {
+  return join(resolveGlobalWildoHomePath(userHome), WORKSPACE_CONFIG_NAMES.PREFERENCES_FILE);
+}
+
+function isPathInside(root: string, target: string): boolean {
+  const rel = relative(resolve(root), resolve(target));
+  return rel === '' || (!rel.startsWith('..') && rel !== '..');
+}
+
+export function resolveConfigArtifactsBaseDir(options: ConfigArtifactsLocationOptions): string;
+export function resolveConfigArtifactsBaseDir(filePath: string): string;
+export function resolveConfigArtifactsBaseDir(
+  input: string | ConfigArtifactsLocationOptions,
+): string {
+  if (typeof input !== 'string') {
+    return resolveConfigArtifactsBaseDirForZone(input);
+  }
+
+  const absolutePath = resolve(input);
+  const scope = resolveWorkspaceScope(dirname(absolutePath));
+
+  if (scope.saasRoot && isPathInside(scope.saasRoot, absolutePath)) {
+    return resolveConfigArtifactsBaseDirForZone({
+      zone: ConfigArtifactsZone.SAAS,
+      ownerRoot: scope.saasRoot,
+    });
+  }
+
+  if (scope.projectRoot && isPathInside(scope.projectRoot, absolutePath)) {
+    return resolveConfigArtifactsBaseDirForZone({
+      zone: ConfigArtifactsZone.PROJECT,
+      ownerRoot: scope.projectRoot,
+    });
+  }
+
+  if (scope.frameworkRoot && isPathInside(scope.frameworkRoot, absolutePath)) {
+    return resolveConfigArtifactsBaseDirForZone({
+      zone: ConfigArtifactsZone.FRAMEWORK,
+      ownerRoot: scope.frameworkRoot,
+    });
+  }
+
+  return resolveConfigArtifactsBaseDirForZone({
+    zone: ConfigArtifactsZone.TEMP,
+    ownerRoot: absolutePath,
+  });
+}
+
+/**
+ * Resolve the canonical runtime-owned base directory for config-loader
+ * artifacts. This keeps Jiti/SWC output out of authored declaration trees and
+ * anchors it under the matching runtime zone.
+ */
+export function resolveConfigArtifactsBaseDirForZone(options: ConfigArtifactsLocationOptions): string {
+  switch (options.zone) {
+    case ConfigArtifactsZone.FRAMEWORK:
+      return join(options.ownerRoot, WORKSPACE_CONFIG_NAMES.FRAMEWORK_DIR, 'dist', 'config-loader', 'framework');
+    case ConfigArtifactsZone.PLATFORM:
+      return join(options.ownerRoot, WORKSPACE_CONFIG_NAMES.PROJECT_DIR, 'dist', 'config-loader', 'platform');
+    case ConfigArtifactsZone.PROJECT:
+      return join(options.ownerRoot, WORKSPACE_CONFIG_NAMES.PROJECT_DIR, 'dist', 'config-loader', 'project');
+    case ConfigArtifactsZone.SAAS:
+      return join(options.ownerRoot, WORKSPACE_CONFIG_NAMES.SAAS_DIR, 'dist', 'config-loader', 'saas');
+    case ConfigArtifactsZone.TEMP:
+      return join(tmpdir(), 'wildo-jiti-cache');
+  }
+}
+
+export function resolveProjectPlatformRoot(
+  projectRoot: string,
+  platformPath: string = WORKSPACE_CONFIG_NAMES.PLATFORM_DIR,
+): string {
+  return join(projectRoot, platformPath);
+}
+
+export function resolveProjectPlatformFilePath(
+  projectRoot: string,
+  platformPath: string = WORKSPACE_CONFIG_NAMES.PLATFORM_DIR,
+  ...segments: string[]
+): string {
+  return join(resolveProjectPlatformRoot(projectRoot, platformPath), ...segments);
+}
+
+/**
+ * Resolve the directory holding project-scoped platform files for one environment.
+ * The environment named `local` lives in `<platformPath>/local/`, while all other
+ * environment ids live in `<platformPath>/remotes/{envName}/`.
+ */
+export function resolveProjectPlatformEnvironmentDir(
+  projectRoot: string,
+  envName: string,
+  platformPath: string = WORKSPACE_CONFIG_NAMES.PLATFORM_DIR,
+): string {
+  if (envName === 'local') {
+    return resolveProjectPlatformFilePath(projectRoot, platformPath, 'local');
+  }
+
+  return resolveProjectPlatformFilePath(projectRoot, platformPath, 'remotes', envName);
+}
+
+/**
+ * Resolve the sharing policy file path for a given environment.
+ * Handles the directory convention used by `resolveProjectPlatformEnvironmentDir()`:
+ * the environment named `local` lives in `<platformPath>/local/`, while all other
+ * environment ids live in `<platformPath>/remotes/{envName}/`.
+ */
+export function resolveSharingPolicyPath(
+  projectRoot: string,
+  envName: string,
+  platformPath: string = WORKSPACE_CONFIG_NAMES.PLATFORM_DIR,
+): string {
+  const fileName = `${WORKSPACE_CONFIG_NAMES.SHARING_POLICY_PREFIX}${envName}.ts`;
+  return join(resolveProjectPlatformEnvironmentDir(projectRoot, envName, platformPath), fileName);
+}