@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/project/file-class.mjs

@@ -1,3 +1,5 @@
+import fs from 'node:fs'
+import path from 'node:path'
 import { basenameOf, matchesPathPattern, normalizeRelPath } from './path-match.mjs'
 
 export const FILE_CLASS_SCHEMA = 'mnstry.atelier-file-classes@v1'
@@ -6,8 +8,13 @@ export const SOURCE = 'source'
 export const GENERATED_PROJECTION = 'generated-projection'
 export const DISTRIBUTED_RUNTIME_COPY = 'distributed-runtime-copy'
 
+// Declarable classes for tracked files. The kit manifest schema closes this set.
 export const FILE_CLASSES = Object.freeze([SOURCE, GENERATED_PROJECTION, DISTRIBUTED_RUNTIME_COPY])
 
+// A machine-local file that git never tracks. It is not declarable: nothing
+// tracked can be ignored-local, so it stays out of FILE_CLASSES.
+export const IGNORED_LOCAL = 'ignored-local'
+
 // What each class means for automated handling. Sync loops, merge policies, upgrade
 // tooling, and CI guards all read this instead of each keeping a list of filenames
 // that drifts out of step with the others.
@@ -15,8 +22,17 @@ export const FILE_CLASS_HANDLING = Object.freeze({
   [SOURCE]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
   [GENERATED_PROJECTION]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
   [DISTRIBUTED_RUNTIME_COPY]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
+  // Holds this machine's only reference to external editable state. Never
+  // swept, never synced, never a merge conflict.
+  [IGNORED_LOCAL]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: false }),
 })
 
+// The one repo-local file the Obsidian view leaves in a repository or
+// workspace: a pointer to the external data directory and its local settings.
+// It lives under the existing ignored local-state directory.
+export const OBSIDIAN_LOCAL_POINTER = '.atelier-local/obsidian.json'
+export const IGNORED_LOCAL_PATTERNS = Object.freeze([`**/${OBSIDIAN_LOCAL_POINTER}`])
+
 // The kit's own declaration — the single place these paths are classified. A
 // distributed-runtime-copy is canonical in exactly one repo role and rederivable
 // everywhere else; that is why the class carries `canonicalRepoRole` rather than
@@ -75,6 +91,12 @@ export function validateFileClasses(entries, { label = 'fileClasses' } = {}) {
  */
 export function classifyPath(filePath, { repoRole = null, fileClasses = KIT_FILE_CLASSES } = {}) {
   const rel = normalizeRelPath(filePath)
+  // Not overridable: a declaration cannot turn a local pointer into something
+  // a sync loop may discard or commit.
+  const localPattern = IGNORED_LOCAL_PATTERNS.find((pattern) => matchesPathPattern(pattern, rel))
+  if (localPattern) {
+    return { path: rel, class: IGNORED_LOCAL, pattern: localPattern, canonicalRepoRole: null, canonicalHere: true, declared: false, handling: FILE_CLASS_HANDLING[IGNORED_LOCAL] }
+  }
   let matched = null
   for (const entry of fileClasses) {
     if (matchesPathPattern(entry.pattern, rel)) matched = entry
@@ -111,3 +133,161 @@ export function generatedProjectionBasenames(fileClasses = KIT_FILE_CLASSES) {
   }
   return names
 }
+
+// Directory basenames whose complete subtree is generated. Graph walkers can
+// prune these without restating output-root names beside the declaration.
+export function generatedProjectionDirectoryBasenames(fileClasses = KIT_FILE_CLASSES) {
+  const names = new Set()
+  for (const entry of fileClasses) {
+    if (entry.class !== GENERATED_PROJECTION) continue
+    const normalized = normalizeRelPath(entry.pattern)
+    if (!normalized.endsWith('/**')) continue
+    const parent = normalized.slice(0, -3).split('/').at(-1)
+    if (parent && !parent.includes('*')) names.add(parent)
+  }
+  return names
+}
+
+// ---------------------------------------------------------------------------
+// External managed data root: <data>/obsidian/<workspace-id>/
+// ---------------------------------------------------------------------------
+
+export const EDITABLE_VAULT = 'editable-vault'
+export const TRUSTED_STATE = 'trusted-state'
+export const RECOVERY_RECORD = 'recovery-record'
+export const DISPOSABLE_STAGING = 'disposable-staging'
+export const UNKNOWN_MANAGED = 'unknown-managed'
+
+// Only staging is discardable. A vault holds a person's edits and recovery
+// holds the only other copy of them, so neither is ever generated output, and
+// anything unrecognized is kept.
+export const MANAGED_AREA_HANDLING = Object.freeze({
+  [EDITABLE_VAULT]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [TRUSTED_STATE]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [RECOVERY_RECORD]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+  [DISPOSABLE_STAGING]: Object.freeze({ rederivable: true, discardable: true, conflictsNeedHuman: false }),
+  [UNKNOWN_MANAGED]: Object.freeze({ rederivable: false, discardable: false, conflictsNeedHuman: true }),
+})
+
+const MANAGED_AREAS = Object.freeze({ vaults: EDITABLE_VAULT, state: TRUSTED_STATE, recovery: RECOVERY_RECORD, staging: DISPOSABLE_STAGING })
+
+// Classify a path relative to one workspace's managed data root. Matching is
+// exact and case-sensitive, and a path that climbs, is absolute or names only
+// the area directory itself is never discardable.
+export function classifyManagedPath(relativePath) {
+  const rel = normalizeRelPath(relativePath).replace(/\/+$/, '')
+  const segments = rel.split('/')
+  const contained = rel !== '' && !rel.startsWith('/') && !/^[A-Za-z]:/.test(rel) && !segments.some((part) => part === '..' || part === '.' || part === '')
+  const area = contained && segments.length > 1 && Object.hasOwn(MANAGED_AREAS, segments[0]) ? segments[0] : null
+  const resolved = area ? MANAGED_AREAS[area] : UNKNOWN_MANAGED
+  return { path: rel, area, class: resolved, handling: MANAGED_AREA_HANDLING[resolved] }
+}
+
+// The real path of a target that may not exist yet: the deepest existing
+// ancestor is resolved and the missing tail is appended. Only "does not exist"
+// moves up a level. Any other failure (a directory that cannot be searched,
+// a link loop) is thrown: a lexical path standing in for a real one would
+// weaken the alias check exactly where it matters.
+function realLocation(target, realpath) {
+  const missing = []
+  let current = path.resolve(target)
+  for (;;) {
+    try {
+      return path.join(realpath(current), ...missing.reverse())
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') throw error
+      const parent = path.dirname(current)
+      if (parent === current) return path.resolve(target)
+      missing.push(path.basename(current))
+      current = parent
+    }
+  }
+}
+
+const containsPath = (outer, inner) => inner === outer || inner.startsWith(outer.endsWith(path.sep) ? outer : `${outer}${path.sep}`)
+
+function isSymbolicLink(target, lstat) {
+  try {
+    return lstat(target).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+// True when the path or any of its ancestors is a symbolic link.
+function crossesSymbolicLink(target, lstat) {
+  for (let current = path.resolve(target); ; current = path.dirname(current)) {
+    if (isSymbolicLink(current, lstat)) return true
+    if (path.dirname(current) === current) return false
+  }
+}
+
+// Refuse a managed root that overlaps an enrolled repository in either
+// direction, under lexical or real paths. `realpath` and `lstat` are the only
+// filesystem reads, and both can be supplied; nothing is created or changed.
+// A real path that cannot be established refuses; it is never replaced by the
+// lexical path.
+export function checkManagedRoots({ managedRoots = [], repositoryRoots = [], realpath = fs.realpathSync.native, lstat = fs.lstatSync } = {}) {
+  const refusals = []
+  const refuse = (code, managedRoot, repositoryRoot, message) => refusals.push({ code, managedRoot, repositoryRoot, message })
+  const locate = (root) => {
+    try {
+      return { given: root, lexical: path.resolve(root), real: realLocation(root, realpath) }
+    } catch (error) {
+      return { given: root, lexical: path.resolve(root), real: null, errorCode: error?.code ?? 'unknown' }
+    }
+  }
+  const repositories = repositoryRoots.map(locate)
+
+  for (const managedRoot of managedRoots) {
+    if (typeof managedRoot !== 'string' || !path.isAbsolute(managedRoot)) {
+      refuse('managed-root-not-absolute', managedRoot, null, 'a managed root must be an absolute path')
+      continue
+    }
+    const managed = locate(managedRoot)
+    if (managed.real === null) {
+      refuse('managed-root-realpath-failed', managedRoot, null, `the real path of a managed root cannot be established (${managed.errorCode})`)
+      continue
+    }
+    if (isSymbolicLink(managed.lexical, lstat)) {
+      refuse('managed-root-symlink-alias', managedRoot, null, 'a managed root must not be a symbolic link')
+    }
+    for (const repository of repositories) {
+      const inside = (kind) => containsPath(repository[kind], managed[kind])
+      const around = (kind) => containsPath(managed[kind], repository[kind])
+      if (inside('lexical')) refuse('managed-root-inside-repository', managedRoot, repository.given, 'a managed root must sit outside every enrolled repository')
+      else if (around('lexical')) refuse('repository-inside-managed-root', managedRoot, repository.given, 'an enrolled repository must not sit inside a managed root')
+      else if (repository.real === null) {
+        refuse('managed-root-realpath-failed', managedRoot, repository.given, `the real path of an enrolled repository cannot be established (${repository.errorCode})`)
+      } else if (inside('real') || around('real')) {
+        // Name the cause that is actually there. Folding letter case and
+        // Unicode normalization alone may explain the overlap; otherwise a
+        // symbolic link on either path does; otherwise something else presents
+        // one location under two names (a mount, for example).
+        const folded = (value) => value.normalize('NFC').toLowerCase()
+        const byFolding = containsPath(folded(repository.lexical), folded(managed.lexical)) || containsPath(folded(managed.lexical), folded(repository.lexical))
+        if (!byFolding && (crossesSymbolicLink(managed.lexical, lstat) || crossesSymbolicLink(repository.lexical, lstat))) {
+          refuse('managed-root-symlink-alias', managedRoot, repository.given, 'a symbolic link makes the managed root and an enrolled repository overlap')
+        } else {
+          refuse('managed-root-realpath-overlap', managedRoot, repository.given,
+            'the managed root and an enrolled repository are written differently but name overlapping locations, and no symbolic link explains it: look for a difference in letter case or Unicode normalization on a filesystem that folds them, or a mount that presents one location under two names')
+        }
+      }
+    }
+  }
+  return { ok: refusals.length === 0, refusals }
+}
+
+// The same guard at enrolment time: a repository that would contain, sit
+// inside or alias an existing managed root cannot be enrolled.
+export function checkRepositoryEnrollment({ repositoryRoot, managedRoots = [], realpath, lstat } = {}) {
+  const { refusals } = checkManagedRoots({ managedRoots, repositoryRoots: [repositoryRoot], ...(realpath ? { realpath } : {}), ...(lstat ? { lstat } : {}) })
+  const codes = {
+    'managed-root-inside-repository': 'enrollment-contains-managed-root',
+    'repository-inside-managed-root': 'enrollment-inside-managed-root',
+    'managed-root-symlink-alias': 'enrollment-aliases-managed-root',
+    'managed-root-realpath-overlap': 'enrollment-realpath-overlaps-managed-root',
+  }
+  const blocking = refusals.filter((item) => item.repositoryRoot !== null).map((item) => ({ ...item, code: codes[item.code] ?? item.code }))
+  return { ok: blocking.length === 0, refusals: blocking }
+}

package/src/project/package-root.mjs

@@ -0,0 +1,10 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export function nativePathFromFileUrl(value) {
+  return fileURLToPath(value instanceof URL ? value : new URL(value))
+}
+
+export function packageRootFrom(moduleUrl) {
+  return path.resolve(nativePathFromFileUrl(new URL('../..', moduleUrl)))
+}

package/src/project/path-match.mjs

@@ -4,27 +4,50 @@ export const normalizeRelPath = (value) =>
   String(value ?? '')
     .replaceAll('\\', '/')
     .replace(/^\.\/+/, '')
+    .replace(/\/{2,}/g, '/')
 
 const escapeRe = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-// Shared by the boundary policy and the file-class resolver. Both used to carry
-// their own copy; two glob dialects in one kit is exactly the drift this file exists
-// to prevent.
+function globSource(pattern) {
+  let source = ''
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char !== '*') {
+      source += escapeRe(char)
+      continue
+    }
+
+    const globstar = pattern[index + 1] === '*'
+    if (!globstar) {
+      source += '[^/]*'
+      continue
+    }
+
+    index += 1
+    if (pattern[index + 1] === '/') {
+      index += 1
+      source += '(?:.*/)?'
+    } else if (source.endsWith('/')) {
+      source = source.slice(0, -1)
+      source += '(?:/.*)?'
+    } else {
+      source += '.*'
+    }
+  }
+  return source
+}
+
+// Shared by the boundary policy and the file-class resolver. The dialect is
+// intentionally portable: case does not depend on the host filesystem, `*`
+// stays inside one segment, and `**` crosses segments. Slashless patterns keep
+// their historical match-base behavior, so `*.md` applies at any depth without
+// making `private/*.md` consume nested directories.
 export function matchesPathPattern(pattern, rel) {
   const normalizedPattern = normalizeRelPath(pattern)
   const normalizedRel = normalizeRelPath(rel)
-  if (normalizedPattern === normalizedRel) return true
-  if (normalizedPattern.endsWith('/**')) {
-    return normalizedRel === normalizedPattern.slice(0, -3) || normalizedRel.startsWith(normalizedPattern.slice(0, -2))
-  }
-  if (normalizedPattern.startsWith('**/')) {
-    const tail = normalizedPattern.slice(3)
-    return normalizedRel === tail || normalizedRel.endsWith(`/${tail}`) || matchesPathPattern(tail, normalizedRel)
-  }
-  if (normalizedPattern.includes('*')) {
-    return new RegExp(`^${normalizedPattern.split('*').map(escapeRe).join('.*')}$`).test(normalizedRel)
-  }
-  return false
+  if (!normalizedPattern || !normalizedRel) return false
+  const candidate = normalizedPattern.includes('/') ? normalizedRel : path.posix.basename(normalizedRel)
+  return new RegExp(`^${globSource(normalizedPattern)}$`, 'i').test(candidate)
 }
 
 export const basenameOf = (pattern) => path.posix.basename(normalizeRelPath(pattern))

package/src/project/private-state.mjs

@@ -0,0 +1,120 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+function escapes(root, candidate) {
+  const relative = path.relative(root, candidate)
+  return relative.startsWith('..') || path.isAbsolute(relative)
+}
+
+function lstatIfPresent(file) {
+  try {
+    return fs.lstatSync(file)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+export function ensureContainedPrivateDirectory({ workspaceRoot, directory, label = 'private state directory' }) {
+  const lexicalRoot = path.resolve(workspaceRoot)
+  const realRoot = fs.realpathSync(lexicalRoot)
+  const requested = path.resolve(directory)
+  let relative = path.relative(lexicalRoot, requested)
+  if (escapes(lexicalRoot, requested)) relative = path.relative(realRoot, requested)
+  if (relative === '' || escapes(realRoot, path.join(realRoot, relative))) {
+    if (relative === '') return realRoot
+    throw new Error(`${label} escapes workspace`)
+  }
+
+  let current = realRoot
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment)
+    let stat = lstatIfPresent(current)
+    if (!stat) {
+      fs.mkdirSync(current, { mode: 0o700 })
+      stat = fs.lstatSync(current)
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`${label} contains a redirected or non-directory component`)
+    }
+  }
+  const resolved = fs.realpathSync(current)
+  if (escapes(realRoot, resolved)) throw new Error(`${label} escapes workspace`)
+  try {
+    fs.chmodSync(resolved, 0o700)
+  } catch {
+    // Best effort on filesystems that do not support chmod.
+  }
+  return resolved
+}
+
+export function openRegularFileNoFollow(file, flags = fs.constants.O_RDONLY, mode) {
+  const before = lstatIfPresent(file)
+  if (before && (before.isSymbolicLink() || !before.isFile())) {
+    throw new Error('state leaf is not a regular file')
+  }
+  const descriptor = fs.openSync(file, flags | (fs.constants.O_NOFOLLOW ?? 0), mode)
+  try {
+    const opened = fs.fstatSync(descriptor)
+    if (!opened.isFile()) throw new Error('state leaf is not a regular file')
+    // Windows does not expose O_NOFOLLOW. Refuse a pre-existing redirected
+    // leaf before open and bind the opened descriptor back to that same file
+    // identity where the filesystem supplies stable device/inode values.
+    if (before && before.ino !== 0 && (before.dev !== opened.dev || before.ino !== opened.ino)) {
+      throw new Error('state leaf changed while opening')
+    }
+    return descriptor
+  } catch (error) {
+    fs.closeSync(descriptor)
+    throw error
+  }
+}
+
+export function readRegularTextNoFollow(file) {
+  const descriptor = openRegularFileNoFollow(file)
+  try {
+    return fs.readFileSync(descriptor, 'utf8')
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}
+
+export function syncPrivateDirectory(directory) {
+  let fd;
+  try { fd = fs.openSync(directory, fs.constants.O_RDONLY); fs.fsyncSync(fd); }
+  catch (error) {
+    if (process.platform !== 'win32' || !['EPERM', 'EACCES', 'EINVAL', 'EISDIR'].includes(error.code)) throw error;
+  } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+export function atomicReplacePrivateText(file, text, mode = 0o600) {
+  const existing = lstatIfPresent(file)
+  if (existing && (existing.isSymbolicLink() || !existing.isFile())) {
+    throw new Error('state leaf is not a regular file')
+  }
+  const tmp = `${file}.${randomUUID()}.tmp`
+  let descriptor
+  try {
+    descriptor = openRegularFileNoFollow(
+      tmp,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+      mode,
+    )
+    fs.writeFileSync(descriptor, text)
+    fs.fsyncSync(descriptor)
+    fs.fchmodSync(descriptor, mode)
+    fs.closeSync(descriptor)
+    descriptor = null
+    fs.renameSync(tmp, file)
+    syncPrivateDirectory(path.dirname(file))
+  } catch (error) {
+    if (descriptor != null) fs.closeSync(descriptor)
+    try {
+      fs.unlinkSync(tmp)
+    } catch {
+      // The temporary file may not have been created.
+    }
+    throw error
+  }
+}