@ontrails/trails 0.2.0

package/src/trails/project-context.ts

@@ -0,0 +1,613 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from 'node:path';
+
+import { findAppModule } from '@ontrails/cli';
+import {
+  findTrailsConfigPaths,
+  readTrailsProjectIdentity,
+  resolveTrailsProjectRoot,
+  trailsAppEntryRelativePath,
+  trailsLockFileName,
+  trailsSourceRootCandidates,
+} from '@ontrails/config';
+import type {
+  ReadTrailsProjectIdentityResult,
+  ResolvedTrailsWorkspaceApp,
+  TrailsProjectRootResolution,
+} from '@ontrails/config';
+import { deriveSafePath, Result, ValidationError } from '@ontrails/core';
+import { deriveWorkspaceView } from '@ontrails/topography';
+
+export type OperatorModuleSource = 'config' | 'convention' | 'module';
+export type OperatorSelectionProvenance = 'app' | 'cwd' | 'root-dir';
+
+export interface OperatorProjectApp {
+  readonly configured: boolean;
+  readonly id?: string | undefined;
+  readonly lockPath: string;
+  readonly modulePath: string;
+  readonly moduleSource: OperatorModuleSource;
+  readonly root: string;
+  readonly rootDir: string;
+}
+
+interface OperatorProjectContextBase {
+  readonly boundaryDir: string;
+  readonly identity: ReadTrailsProjectIdentityResult;
+  readonly projectRoot: string;
+  readonly selectionProvenance: OperatorSelectionProvenance;
+}
+
+export interface OperatorAppProjectContext extends OperatorProjectContextBase {
+  readonly app: OperatorProjectApp;
+  readonly selectedExtent: 'configured-app' | 'standalone-app';
+}
+
+export interface OperatorWorkspaceProjectContext extends OperatorProjectContextBase {
+  readonly apps: readonly OperatorProjectApp[];
+  readonly selectedExtent: 'workspace';
+}
+
+export type OperatorProjectContext =
+  | OperatorAppProjectContext
+  | OperatorWorkspaceProjectContext;
+
+export interface OperatorProjectContextInput {
+  readonly app?: string | undefined;
+  readonly module?: string | undefined;
+  readonly rootDir?: string | undefined;
+}
+
+export interface OperatorProjectContextRuntime {
+  readonly cwd?: string | undefined;
+}
+
+const URL_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
+
+const isInside = (root: string, target: string): boolean => {
+  const path = relative(root, target);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+};
+
+const canonicalPath = (path: string): string => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+};
+
+const isPreviouslyOwnedSourceMarker = (
+  current: string,
+  candidate: string,
+  markerPath: string,
+  resolvedMarkerPath: string | undefined
+): boolean =>
+  (candidate === 'trails' && basename(current) === 'src') ||
+  canonicalPath(markerPath) === resolvedMarkerPath;
+
+const projectContextError = (
+  message: string,
+  reason:
+    | 'compile-needs-app'
+    | 'invalid-binding'
+    | 'outside-project'
+    | 'unknown-app',
+  context: Record<string, unknown>
+): ValidationError =>
+  new ValidationError(message, { context: { ...context, reason } });
+
+const readGitWorkingTreeBoundary = (cwd: string): string | undefined => {
+  try {
+    const result = Bun.spawnSync({
+      cmd: ['git', '-C', cwd, 'rev-parse', '--show-toplevel'],
+      env: process.env,
+      stderr: 'ignore',
+      stdout: 'pipe',
+    });
+    if (!result.success) {
+      return undefined;
+    }
+    const root = Buffer.from(result.stdout).toString('utf8').trim();
+    return root === '' ? undefined : resolve(root);
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Widen the boundary far enough for overlapping workspace declarations to fail
+ * closed, mirroring the Git working-tree boundary the Git-available path uses.
+ */
+const resolveNonGitCollectionBoundary = async (
+  cwd: string
+): Promise<string> => {
+  let current = cwd;
+  let nearestConfigRoot: string | undefined;
+  let outermostWorkspaceRoot: string | undefined;
+  while (true) {
+    if (findTrailsConfigPaths(current).length > 0) {
+      nearestConfigRoot ??= current;
+      const identity = await readTrailsProjectIdentity({
+        boundaryDir: current,
+        startDir: current,
+      });
+      if (identity.workspace !== undefined) {
+        outermostWorkspaceRoot = identity.rootDir;
+      }
+    }
+    if (existsSync(join(current, '.git'))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return (
+    outermostWorkspaceRoot ??
+    nearestConfigRoot ??
+    resolveTrailsProjectRoot({ startDir: cwd }).rootDir
+  );
+};
+
+/**
+ * Resolve the first-class filesystem collection observed by operator commands.
+ *
+ * @example
+ * ```ts
+ * const boundaryDir = await resolveOperatorCollectionBoundary(process.cwd());
+ * ```
+ */
+export const resolveOperatorCollectionBoundary = async (
+  startDir: string
+): Promise<string> =>
+  readGitWorkingTreeBoundary(startDir) ??
+  (await resolveNonGitCollectionBoundary(startDir));
+
+const configuredApp = (
+  app: ResolvedTrailsWorkspaceApp,
+  moduleOverride?: string | undefined
+): OperatorProjectApp => {
+  let moduleSource: OperatorModuleSource = 'module';
+  if (moduleOverride === undefined) {
+    moduleSource = app.entrySource === 'explicit' ? 'config' : 'convention';
+  }
+  return {
+    configured: true,
+    id: app.id,
+    lockPath: join(app.rootDir, trailsLockFileName),
+    modulePath: moduleOverride ?? app.entry,
+    moduleSource,
+    root: app.root,
+    rootDir: app.rootDir,
+  };
+};
+
+const standaloneApp = (
+  projectRoot: string,
+  moduleOverride: string | undefined
+): OperatorProjectApp => ({
+  configured: false,
+  lockPath: join(projectRoot, trailsLockFileName),
+  modulePath: moduleOverride ?? trailsAppEntryRelativePath,
+  moduleSource: moduleOverride === undefined ? 'convention' : 'module',
+  root: '.',
+  rootDir: projectRoot,
+});
+
+/** Apply canonical module discovery only when a standalone app will be loaded. */
+export const resolveOperatorAppModuleContext = (
+  context: OperatorAppProjectContext
+): Result<OperatorAppProjectContext, Error> => {
+  if (context.app.configured || context.app.moduleSource !== 'convention') {
+    return Result.ok(context);
+  }
+  try {
+    return Result.ok({
+      ...context,
+      app: {
+        ...context.app,
+        modulePath: findAppModule(context.app.rootDir),
+      },
+    });
+  } catch (error) {
+    return Result.err(
+      error instanceof Error
+        ? error
+        : new ValidationError('Unable to discover a Trails app module.', {
+            context: { detail: String(error) },
+          })
+    );
+  }
+};
+
+const unknownAppError = (
+  requestedAppId: string,
+  configuredAppIds: readonly string[],
+  projectRoot: string
+): ValidationError =>
+  projectContextError(
+    configuredAppIds.length === 0
+      ? `App "${requestedAppId}" is not configured. This project has no workspace.apps catalog; omit --app or add the app to workspace.apps.`
+      : `Unknown app "${requestedAppId}". Configured apps: ${configuredAppIds.join(', ')}. Use --app <id> with one of those IDs.`,
+    'unknown-app',
+    { configuredAppIds, projectRoot, requestedAppId }
+  );
+
+const configuredSelection = (
+  input: OperatorProjectContextInput,
+  cwd: string,
+  boundaryDir: string,
+  identity: ReadTrailsProjectIdentityResult,
+  explicitRoot: boolean
+): OperatorProjectContext => {
+  const configuredAppIds = identity.apps.map((app) => app.id);
+  if (input.app !== undefined) {
+    const selected = identity.apps.find((app) => app.id === input.app);
+    if (selected === undefined) {
+      throw unknownAppError(input.app, configuredAppIds, identity.rootDir);
+    }
+    return {
+      app: configuredApp(selected, input.module),
+      boundaryDir,
+      identity,
+      projectRoot: identity.rootDir,
+      selectedExtent: 'configured-app',
+      selectionProvenance: 'app',
+    };
+  }
+
+  const canonicalBoundary = canonicalPath(boundaryDir);
+  const canonicalCwd = canonicalPath(cwd);
+  const selectedByCwd =
+    canonicalCwd !== canonicalBoundary &&
+    isInside(canonicalBoundary, canonicalCwd);
+  const selectionPoint = selectedByCwd ? cwd : boundaryDir;
+  let selectionProvenance: OperatorSelectionProvenance = explicitRoot
+    ? 'root-dir'
+    : 'cwd';
+  if (selectedByCwd) {
+    selectionProvenance = 'cwd';
+  }
+  if (canonicalPath(selectionPoint) === canonicalPath(identity.rootDir)) {
+    if (input.module !== undefined) {
+      throw projectContextError(
+        '--module cannot select one app from a workspace extent. Add --app <id> before refining its module.',
+        'invalid-binding',
+        {
+          configuredAppIds,
+          module: input.module,
+          projectRoot: identity.rootDir,
+        }
+      );
+    }
+    return {
+      apps: identity.apps.map((app) => configuredApp(app)),
+      boundaryDir,
+      identity,
+      projectRoot: identity.rootDir,
+      selectedExtent: 'workspace',
+      selectionProvenance,
+    };
+  }
+
+  const containingApps = identity.apps.filter((app) =>
+    isInside(canonicalPath(app.rootDir), canonicalPath(selectionPoint))
+  );
+  if (containingApps.length !== 1) {
+    throw projectContextError(
+      containingApps.length === 0
+        ? `Current directory ${selectionPoint} is inside workspace ${identity.rootDir} but not inside a configured app root. Run from the workspace root for workspace extent or pass --app <id>.`
+        : `Current directory ${selectionPoint} is inside overlapping configured app roots: ${containingApps.map((app) => app.id).join(', ')}. Make workspace.apps roots non-overlapping.`,
+      containingApps.length === 0 ? 'outside-project' : 'invalid-binding',
+      {
+        configuredAppIds,
+        cwd: selectionPoint,
+        matchingAppIds: containingApps.map((app) => app.id),
+        projectRoot: identity.rootDir,
+      }
+    );
+  }
+
+  return {
+    app: configuredApp(
+      containingApps[0] as ResolvedTrailsWorkspaceApp,
+      input.module
+    ),
+    boundaryDir,
+    identity,
+    projectRoot: identity.rootDir,
+    selectedExtent: 'configured-app',
+    selectionProvenance,
+  };
+};
+
+const resolveStandaloneRoot = (
+  startDir: string,
+  boundaryDir: string,
+  explicitRoot: boolean,
+  modulePath: string | undefined
+): TrailsProjectRootResolution => {
+  const resolved = resolveTrailsProjectRoot({
+    boundaryDir,
+    ...(explicitRoot ? { explicitRootDir: boundaryDir } : {}),
+    startDir,
+  });
+  if (explicitRoot) {
+    return resolved;
+  }
+
+  let current = resolve(startDir);
+  const discoveredRoot = resolve(resolved.rootDir);
+  const resolvedMarkerPath =
+    resolved.markerPath === undefined
+      ? undefined
+      : canonicalPath(resolved.markerPath);
+  while (true) {
+    if (
+      modulePath !== undefined &&
+      !isAbsolute(modulePath) &&
+      !URL_SCHEME.test(modulePath)
+    ) {
+      const safeModulePath = deriveSafePath(current, modulePath);
+      if (safeModulePath.isOk()) {
+        try {
+          if (statSync(safeModulePath.value).isFile()) {
+            return {
+              marker: 'source',
+              markerPath: safeModulePath.value,
+              rootDir: current,
+            };
+          }
+        } catch {
+          // A missing custom entry is ordinary during the bounded walk.
+        }
+      }
+    }
+    const appEntryPath = join(current, trailsAppEntryRelativePath);
+    try {
+      if (statSync(appEntryPath).isFile()) {
+        return { marker: 'source', markerPath: appEntryPath, rootDir: current };
+      }
+    } catch {
+      // A missing conventional entry is ordinary during the bounded walk.
+    }
+    for (const candidate of trailsSourceRootCandidates) {
+      const markerPath = join(current, candidate);
+      try {
+        if (
+          statSync(markerPath).isDirectory() &&
+          !isPreviouslyOwnedSourceMarker(
+            current,
+            candidate,
+            markerPath,
+            resolvedMarkerPath
+          )
+        ) {
+          return { marker: 'source', markerPath, rootDir: current };
+        }
+      } catch {
+        // Missing source conventions are ordinary during the bounded walk.
+      }
+    }
+    if (current === discoveredRoot) {
+      return resolved;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return resolved;
+    }
+    current = parent;
+  }
+};
+
+export const resolveOperatorProjectContext = async (
+  input: OperatorProjectContextInput,
+  runtime: OperatorProjectContextRuntime
+): Promise<Result<OperatorProjectContext, Error>> => {
+  try {
+    const explicitRoot = input.rootDir !== undefined;
+    const invocationCwd = resolve(runtime.cwd ?? process.cwd());
+    const cwd = explicitRoot ? invocationCwd : canonicalPath(invocationCwd);
+    const boundaryDir = explicitRoot
+      ? resolve(cwd, input.rootDir)
+      : await resolveOperatorCollectionBoundary(cwd);
+    if (!existsSync(boundaryDir)) {
+      throw projectContextError(
+        `Project root ${boundaryDir} does not exist.`,
+        'outside-project',
+        { boundaryDir, cwd }
+      );
+    }
+    const startDir = explicitRoot ? boundaryDir : cwd;
+    const identity = await readTrailsProjectIdentity({
+      boundaryDir,
+      startDir,
+    });
+    if (identity.workspace !== undefined) {
+      return Result.ok(
+        configuredSelection(input, cwd, boundaryDir, identity, explicitRoot)
+      );
+    }
+    if (input.app !== undefined) {
+      throw unknownAppError(input.app, [], identity.rootDir);
+    }
+
+    const root = resolveStandaloneRoot(
+      startDir,
+      boundaryDir,
+      explicitRoot,
+      input.module
+    );
+    return Result.ok({
+      app: standaloneApp(root.rootDir, input.module),
+      boundaryDir,
+      identity: { ...identity, rootDir: root.rootDir },
+      projectRoot: root.rootDir,
+      selectedExtent: 'standalone-app',
+      selectionProvenance: explicitRoot ? 'root-dir' : 'cwd',
+    });
+  } catch (error) {
+    return Result.err(
+      error instanceof Error
+        ? error
+        : new ValidationError('Unable to resolve Trails project context.', {
+            context: { detail: String(error) },
+          })
+    );
+  }
+};
+
+export const compileNeedsAppError = (
+  context: OperatorWorkspaceProjectContext
+): ValidationError => {
+  const configuredAppIds = context.apps.map((app) => app.id as string);
+  return projectContextError(
+    `Workspace compile requires one app and never fans out. Choose: ${configuredAppIds.map((id) => `--app ${id}`).join(', ')}.`,
+    'compile-needs-app',
+    { configuredAppIds, projectRoot: context.projectRoot }
+  );
+};
+
+interface ConfiguredAppBindingExpectation {
+  readonly app: {
+    readonly id?: string | undefined;
+    readonly modulePath: string;
+  };
+  readonly projectRoot: string;
+}
+
+export const assertConfiguredAppBinding = (
+  context: ConfiguredAppBindingExpectation,
+  actualAppId: string
+): Result<void, ValidationError> => {
+  const expectedAppId = context.app.id;
+  if (expectedAppId === undefined || expectedAppId === actualAppId) {
+    return Result.ok();
+  }
+  return Result.err(
+    projectContextError(
+      `Configured app "${expectedAppId}" loaded topo "${actualAppId}". Align workspace.apps, the app topo name, and ${context.app.modulePath}.`,
+      'invalid-binding',
+      {
+        actualAppId,
+        expectedAppId,
+        modulePath: context.app.modulePath,
+        projectRoot: context.projectRoot,
+      }
+    )
+  );
+};
+
+export const assertObservableProjectApps = async (
+  context: OperatorProjectContext
+): Promise<Result<void, ValidationError>> => {
+  if (context.identity.workspace === undefined) {
+    return Result.ok();
+  }
+  const selectedAppIds =
+    context.selectedExtent === 'workspace'
+      ? context.apps.map((app) => app.id as string)
+      : [context.app.id as string];
+  let view: Awaited<ReturnType<typeof deriveWorkspaceView>>;
+  try {
+    view = await deriveWorkspaceView({
+      identity: context.identity,
+      selectedAppIds,
+    });
+  } catch (error) {
+    return Result.err(
+      projectContextError(
+        `Unable to observe configured app collection boundaries: ${error instanceof Error ? error.message : String(error)}.`,
+        'invalid-binding',
+        {
+          appIds: selectedAppIds,
+          detail: error instanceof Error ? error.message : String(error),
+          projectRoot: context.projectRoot,
+        }
+      )
+    );
+  }
+  const unavailable = view.evidence.apps.filter(
+    (app) => selectedAppIds.includes(app.id) && app.status === 'unavailable'
+  );
+  if (unavailable.length === 0) {
+    return Result.ok();
+  }
+  return Result.err(
+    projectContextError(
+      `Configured app collection boundary is unavailable: ${unavailable.map((app) => `${app.id} (${app.detail ?? app.status})`).join(', ')}.`,
+      'invalid-binding',
+      {
+        appIds: selectedAppIds,
+        collectionSkips: view.evidence.collectionSkips,
+        projectRoot: context.projectRoot,
+        unavailable,
+      }
+    )
+  );
+};
+
+/**
+ * Require a configured app's saved artifact to belong to that Config ID.
+ *
+ * @remarks Collection observability and artifact identity are separate facts:
+ * a lock can be readable while naming a different app. Saved app-scoped
+ * consumers must fail closed on that mismatch instead of presenting the
+ * foreign graph under the requested `--app` identity.
+ */
+export const assertSelectedArtifactBinding = async (
+  context: OperatorAppProjectContext
+): Promise<Result<void, ValidationError>> => {
+  if (!context.app.configured || context.app.id === undefined) {
+    return Result.ok();
+  }
+  const view = await deriveWorkspaceView({
+    identity: context.identity,
+    selectedAppIds: [context.app.id],
+  });
+  const observation = view.evidence.apps.find(
+    (candidate) => candidate.id === context.app.id
+  );
+  if (
+    observation !== undefined &&
+    observation.binding !== 'mismatched' &&
+    observation.status !== 'invalid'
+  ) {
+    return Result.ok();
+  }
+  if (observation === undefined) {
+    return Result.err(
+      projectContextError(
+        `Unable to inspect saved artifact binding for configured app "${context.app.id}".`,
+        'invalid-binding',
+        {
+          appId: context.app.id,
+          artifactPath: context.app.lockPath,
+          projectRoot: context.projectRoot,
+        }
+      )
+    );
+  }
+  return Result.err(
+    projectContextError(
+      `Saved artifact for configured app "${context.app.id}" is invalid or does not match its Config-owned identity.`,
+      'invalid-binding',
+      {
+        appId: context.app.id,
+        artifactPath: context.app.lockPath,
+        evidence: observation,
+        projectRoot: context.projectRoot,
+      }
+    )
+  );
+};

package/src/trails/project.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared Trails-project detection helpers for scaffold trails.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { isDraftMarkedFile } from '@ontrails/warden';
+
+/** Return all TypeScript entries in a project's src directory. */
+const sourceEntryPriority = (entry: string): number => {
+  if (entry === 'app.ts') {
+    return 0;
+  }
+  return isDraftMarkedFile(entry) ? 2 : 1;
+};
+
+const scanSourceEntries = (srcDir: string): string[] =>
+  [...new Bun.Glob('*.ts').scanSync({ cwd: srcDir })].toSorted((a, b) => {
+    const priority = sourceEntryPriority(a) - sourceEntryPriority(b);
+    if (priority === 0) {
+      return a.localeCompare(b);
+    }
+    return priority;
+  });
+
+/** Resolve an entry to an app import if it contains topo(). */
+const toTopoImport = async (
+  srcDir: string,
+  entry: string
+): Promise<string | null> => {
+  const content = await Bun.file(join(srcDir, entry)).text();
+  return content.includes('topo(')
+    ? `./${entry.replace(/\.ts$/, '.js')}`
+    : null;
+};
+
+/** Find the app module that defines a topo inside `src/`. */
+export const findTopoPath = async (cwd: string): Promise<string | null> => {
+  const srcDir = join(cwd, 'src');
+  if (!existsSync(srcDir)) {
+    return null;
+  }
+
+  try {
+    for (const entry of scanSourceEntries(srcDir)) {
+      const appImport = await toTopoImport(srcDir, entry);
+      if (appImport) {
+        return appImport;
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+};
+
+/** Detect whether the directory already looks like a Trails project. */
+export const isInsideProject = async (cwd: string): Promise<boolean> => {
+  if (existsSync(join(cwd, '.trails'))) {
+    return true;
+  }
+  return (await findTopoPath(cwd)) !== null;
+};