@pmelab/gtd 63.0.0 → 64.1.0

package/src/twins/SyncIo.ts

@@ -0,0 +1,159 @@
+import { pureHash, type FileInfo, type SyncIo } from "../platform/index.js"
+import type { InMemRepo } from "./InMemRepo.js"
+
+const MAX_LINKS = 40
+
+const fault = (code: string, op: string, path: string): Error =>
+  Object.assign(new Error(`${code}: ${op} '${path}'`), { code })
+
+const parentOf = (path: string): string => path.slice(0, path.lastIndexOf("/")) || "/"
+
+const joined = (dir: string, name: string): string => (dir === "/" ? `/${name}` : `${dir}/${name}`)
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { ignoreBOM: true })
+
+export interface InMemorySyncIo extends SyncIo {
+  readonly symlink: (path: string, target: string) => void
+}
+
+/**
+ * A POSIX file system in memory, absolute paths only. Its git answers the
+ * reads gtd makes from `repo`, rooted at `root`.
+ */
+export const inMemorySyncIo = (
+  opts: { readonly repo?: InMemRepo; readonly root?: string; readonly uid?: number } = {},
+): InMemorySyncIo => {
+  const files = new Map<string, Uint8Array>()
+  const links = new Map<string, string>()
+  const dirs = new Set<string>(["/"])
+
+  /** `path` with every symlink resolved, the last component's only when `followLast`. */
+  const resolve = (path: string, followLast: boolean): string => {
+    let pending = path.split("/").filter((part) => part.length > 0)
+    let at = "/"
+    let hops = 0
+    while (pending.length > 0) {
+      const [name, ...rest] = pending as [string, ...string[]]
+      pending = rest
+      if (name === ".") continue
+      if (name === "..") {
+        at = parentOf(at)
+        continue
+      }
+      const next = joined(at, name)
+      const target = links.get(next)
+      if (target === undefined || (rest.length === 0 && !followLast)) {
+        at = next
+        continue
+      }
+      if (++hops > MAX_LINKS) throw fault("ELOOP", "resolve", path)
+      if (target.startsWith("/")) at = "/"
+      pending = [...target.split("/").filter((part) => part.length > 0), ...rest]
+    }
+    return at
+  }
+
+  const typeOf = (path: string): FileInfo["type"] | undefined =>
+    links.has(path)
+      ? "symlink"
+      : files.has(path)
+        ? "file"
+        : dirs.has(path)
+          ? "directory"
+          : undefined
+
+  const parentExists = (path: string): boolean =>
+    typeOf(resolve(parentOf(path), true)) === "directory"
+
+  const info = (path: string): FileInfo | undefined => {
+    const type = typeOf(path)
+    return type === undefined ? undefined : { type, uid: opts.uid }
+  }
+
+  const readFile = (path: string): Uint8Array | undefined => {
+    const real = resolve(path, true)
+    if (dirs.has(real)) throw fault("EISDIR", "read", path)
+    return files.get(real)
+  }
+
+  const writeFile = (path: string, content: Uint8Array): void => {
+    const real = resolve(path, true)
+    if (!parentExists(real)) throw fault("ENOENT", "open", path)
+    if (dirs.has(real)) throw fault("EISDIR", "open", path)
+    files.set(real, content)
+  }
+
+  const makeDirectory = (path: string): void => {
+    const real = resolve(path, true)
+    const type = typeOf(real)
+    if (type === "directory") return
+    if (type !== undefined) throw fault("EEXIST", "mkdir", path)
+    makeDirectory(parentOf(real))
+    dirs.add(real)
+  }
+
+  const show = (repo: InMemRepo, spec: string): string => {
+    const colon = spec.indexOf(":")
+    const content = repo.fileAtRef(spec.slice(0, colon), spec.slice(colon + 1))
+    if (content === null) throw new Error(`fatal: invalid object name '${spec}'`)
+    return content
+  }
+
+  const revParse = (repo: InMemRepo, arg: string): string => {
+    if (arg === "--show-object-format") return "sha1\n"
+    const hash = repo.resolveRef(arg)
+    if (hash === null) throw new Error(`fatal: ambiguous argument '${arg}'`)
+    return `${hash}\n`
+  }
+
+  const git = (cwd: string, args: readonly string[]): string => {
+    const { repo, root } = opts
+    if (repo === undefined || resolve(cwd, true) !== root) {
+      throw new Error(`fatal: not a git repository: ${cwd}`)
+    }
+    const [command, arg, ...rest] = args
+    if (arg === undefined || rest.length > 0 || (command !== "show" && command !== "rev-parse")) {
+      throw new Error(`in-memory git: unsupported \`git ${args.join(" ")}\``)
+    }
+    return command === "show" ? show(repo, arg) : revParse(repo, arg)
+  }
+
+  return {
+    readFile,
+    readText: (path) => {
+      const bytes = readFile(path)
+      return bytes === undefined ? undefined : decoder.decode(bytes)
+    },
+    writeText: (path, content) => writeFile(path, encoder.encode(content)),
+    makeDirectory,
+    rename: (from, to) => {
+      const source = resolve(from, false)
+      const target = resolve(to, false)
+      const bytes = files.get(source)
+      if (bytes === undefined) throw fault("ENOENT", "rename", from)
+      if (!parentExists(target)) throw fault("ENOENT", "rename", to)
+      links.delete(target)
+      files.set(target, bytes)
+      files.delete(source)
+    },
+    stat: (path) => info(resolve(path, true)),
+    lstat: (path) => info(resolve(path, false)),
+    readLink: (path) => {
+      const target = links.get(resolve(path, false))
+      if (target === undefined) throw fault("EINVAL", "readlink", path)
+      return target
+    },
+    realPath: (path) => {
+      const real = resolve(path, true)
+      if (typeOf(real) === undefined) throw fault("ENOENT", "realpath", path)
+      return real
+    },
+    git,
+    gitBytes: (cwd, args) => encoder.encode(git(cwd, args)),
+    hash: pureHash,
+    symlink: (path, target) => {
+      links.set(resolve(path, false), target)
+    },
+  }
+}

package/src/twins/cliIo.ts

@@ -14,6 +14,7 @@ export const makeCapturingCliIo = (
   repo: InMemRepo,
   env: Readonly<Record<string, string | undefined>> = {},
   tools: Partial<ToolCommands["Service"]> = {},
+  stdin = "",
 ): { readonly io: CliIo; readonly result: () => CapturedCliResult } => {
   let stdout: Buffer = Buffer.alloc(0)
   let stderr = ""
@@ -32,7 +33,13 @@ export const makeCapturingCliIo = (
     // errors into — narration lands in the exact same buffer, exactly like a
     // real invocation's narration and remediation share one fd.
     layers: (verbose) =>
-      testLayers(repo, { env, narrate: (line) => (stderr += line), verbose, tools }),
+      testLayers(repo, {
+        env,
+        narrate: (line) => (stderr += line),
+        verbose,
+        tools,
+        stdin,
+      }),
   }
   return {
     io,

package/src/twins/index.ts

@@ -1,5 +1,9 @@
 export { InMemRepo } from "./InMemRepo.js"
 export {
+  inMemPath,
+  inMemoryHost,
+  IN_MEMORY_PID,
+  IN_MEMORY_SCRATCH,
   makeInMemoryWorkspaceOps,
   testLayers,
   type CommandTable,
@@ -13,3 +17,4 @@ export { strictGitOperations } from "./StrictGitOperations.js"
 export { fakeGitOperations } from "./FakeGitOperations.js"
 export { takePinBeat } from "./PinBeats.js"
 export { inMemPinFile } from "./PinFile.js"
+export { inMemorySyncIo } from "./SyncIo.js"

package/src/workflow/SteeringFormats.ts

@@ -4,3 +4,7 @@ export const seededValidateCommand = (mode: string): string => `gtd check ${mode
 /** True when `command` is exactly `mode`'s seeded template (compared literally, not rendered) — distinguishes gtd's own seeding from a user override. */
 export const isSeededValidateCommand = (mode: string, command: string): boolean =>
   command === seededValidateCommand(mode)
+
+/** The `validate:` command for a declared format: its spec travels on the command line, so `gtd check` loads no workflow to find it. */
+export const declaredValidateCommand = (mode: string, spec: string): string =>
+  `gtd check ${mode} "$GTD_FILE" --spec '${spec.replace(/'/g, "'\\''")}'`

package/src/workflow/Workflow.ts

@@ -32,6 +32,8 @@ export interface StepDef {
   readonly label?: string
   readonly file?: string
   readonly mode?: StateMode
+  /** A declared format's spec, when `mode` names one rather than a built-in or `modes:` entry. */
+  readonly modeSpec?: string
   readonly model?: string
   readonly system?: string
   readonly judge?: string

package/src/workflow/discovery.test.ts

@@ -2,7 +2,7 @@ import { execSync } from "node:child_process"
 import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { dirname, join } from "node:path"
-import { Effect, Layer } from "effect"
+import { Effect, Layer, type Path } from "effect"
 import { afterEach, describe, expect, it } from "vitest"
 import { GitService, Host, Narrator, Workspace, NodeServices } from "../platform/index.js"
 import { InMemRepo, testLayers } from "../twins/index.js"
@@ -34,7 +34,7 @@ const config = (imports: string): string =>
   ].join("\n")
 
 const loadWith = (
-  layer: Layer.Layer<ConfigService | Narrator | Workspace | Host | ConfigDiscovery>,
+  layer: Layer.Layer<ConfigService | Narrator | Workspace | Host | Path.Path | ConfigDiscovery>,
 ) =>
   Effect.runPromise(
     Effect.flatMap(ConfigService, (service) => service.load).pipe(
@@ -63,15 +63,16 @@ const live = (): Tier => {
       }
       const host = Host.layer({ root, home: root, env: {} })
       const git = GitService.Live.pipe(Layer.provide(Layer.merge(host, NodeServices.layer)))
-      const workspace = Workspace.Live.pipe(Layer.provide(Layer.merge(host, git)))
+      const workspace = Workspace.Live.pipe(
+        Layer.provide(Layer.mergeAll(host, git, NodeServices.layer)),
+      )
       return loadWith(
         Layer.mergeAll(
           ConfigService.Live,
           ConfigDiscovery.Live,
-          host,
           workspace,
           Narrator.layer(() => {}, false),
-        ),
+        ).pipe(Layer.provideMerge(host), Layer.provideMerge(NodeServices.layer)),
       )
     },
     dispose: () => rmSync(root, { recursive: true, force: true }),

package/src/workflow/discovery.ts

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync, statSync } from "node:fs"
-import { dirname, join } from "node:path"
-import { Context, Effect, Layer } from "effect"
+import { Context, Effect, Layer, Path } from "effect"
+import { Host, nodeSyncIo, type SyncIo } from "../platform/index.js"
 
 /** The workflow module found on the cwd→home walk, with its source. */
 export interface WorkflowModule {
@@ -50,17 +49,21 @@ export const LEGACY_RC_FILES = [
 ]
 
 /** The directories searched for a leftover rc file: the walk, plus `home` when the walk misses it. */
-export const legacyRcDirs = (root: string, home: string): readonly string[] => {
-  const chain = walkUp(root, home)
+export const legacyRcDirs = (path: Path.Path, root: string, home: string): readonly string[] => {
+  const chain = walkUp(path, root, home)
   return chain.includes(home) ? chain : [...chain, home]
 }
 
-const legacyRcFileAt = (path: string): LegacyRcFile | undefined => {
+const legacyRcFileAt = (
+  io: SyncIo,
+  path: string,
+  uid: number | undefined,
+): LegacyRcFile | undefined => {
   try {
-    const stat = statSync(path)
-    if (!stat.isFile()) return undefined
+    const stat = io.stat(path)
+    if (stat?.type !== "file") return undefined
     // Above home, a shared directory (`/tmp`) can hold another user's file.
-    return { path, owned: process.getuid === undefined || stat.uid === process.getuid() }
+    return { path, owned: uid === undefined || stat.uid === uid }
   } catch {
     return undefined
   }
@@ -74,40 +77,43 @@ const legacyRcFileAt = (path: string): LegacyRcFile | undefined => {
  * shared implementation, not a second copy in `src/twins/Layers.ts` that
  * could silently diverge.
  */
-export const walkUp = (from: string, home: string): ReadonlyArray<string> => {
+export const walkUp = (path: Path.Path, from: string, home: string): ReadonlyArray<string> => {
   const chain: Array<string> = []
   let dir = from
   while (true) {
     chain.push(dir)
     if (dir === home) break
-    const parent = dirname(dir)
+    const parent = path.dirname(dir)
     if (parent === dir) break // filesystem root
     dir = parent
   }
   return chain
 }
 
-const legacyRcFiles = (root: string, home: string): Effect.Effect<readonly LegacyRcFile[], Error> =>
-  Effect.sync(() =>
-    legacyRcDirs(root, home).flatMap((dir) =>
-      LEGACY_RC_FILES.flatMap((name) => legacyRcFileAt(join(dir, name)) ?? []),
+const liveDiscovery = (
+  io: SyncIo,
+  path: Path.Path,
+  uid: number | undefined,
+): ConfigDiscoveryOps => ({
+  legacyRcFiles: (root, home) =>
+    Effect.sync(() =>
+      legacyRcDirs(path, root, home).flatMap((dir) =>
+        LEGACY_RC_FILES.flatMap((name) => legacyRcFileAt(io, path.join(dir, name), uid) ?? []),
+      ),
     ),
-  )
-
-const workflowModule = (
-  root: string,
-  home: string,
-): Effect.Effect<WorkflowModule | undefined, Error> =>
-  Effect.try({
-    try: () => {
-      for (const dir of walkUp(root, home)) {
-        const filepath = join(dir, WORKFLOW_MODULE)
-        if (existsSync(filepath)) return { filepath, source: readFileSync(filepath, "utf8") }
-      }
-      return undefined
-    },
-    catch: (e) => (e instanceof Error ? e : new Error(String(e))),
-  })
+  workflowModule: (root, home) =>
+    Effect.try({
+      try: () => {
+        for (const dir of walkUp(path, root, home)) {
+          const filepath = path.join(dir, WORKFLOW_MODULE)
+          const source = io.readText(filepath)
+          if (source !== undefined) return { filepath, source }
+        }
+        return undefined
+      },
+      catch: (e) => (e instanceof Error ? e : new Error(String(e))),
+    }),
+})
 
 /**
  * The discovery seam — a `Context.Service`, not part of `WorkflowFiles` (that
@@ -122,5 +128,10 @@ const workflowModule = (
 export class ConfigDiscovery extends Context.Service<ConfigDiscovery, ConfigDiscoveryOps>()(
   "ConfigDiscovery",
 ) {
-  static Live = Layer.succeed(ConfigDiscovery, { legacyRcFiles, workflowModule })
+  static Live = Layer.effect(
+    ConfigDiscovery,
+    Effect.gen(function* () {
+      return liveDiscovery(nodeSyncIo, yield* Path.Path, (yield* Host).uid)
+    }),
+  )
 }

package/src/workflow/fingerprint.test.ts

@@ -9,6 +9,8 @@ import {
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { describe, expect, it } from "vitest"
+import { nodeSyncIo } from "../platform/index.js"
+import { inMemPath } from "../twins/index.js"
 import { changedConfigFiles, configFingerprint } from "./fingerprint.js"
 
 const read = (path: string): string | undefined => {
@@ -27,6 +29,8 @@ describe("the config fingerprint", () => {
     writeFileSync(join(root, "lib", "flow.ts"), "export const a = 1\n")
 
     const fingerprint = configFingerprint(
+      nodeSyncIo,
+      inMemPath,
       [join(root, "gtd.config.ts"), join(root, "lib", "flow.ts"), join(root, "gone.ts")],
       root,
       read,
@@ -38,7 +42,13 @@ describe("the config fingerprint", () => {
     expect(
       changedConfigFiles(
         fingerprint,
-        configFingerprint([join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")], root, read),
+        configFingerprint(
+          nodeSyncIo,
+          inMemPath,
+          [join(root, "gtd.config.ts"), join(root, "lib", "flow.ts")],
+          root,
+          read,
+        ),
       ),
     ).toEqual(["lib/flow.ts"])
   })
@@ -50,7 +60,15 @@ describe("the config fingerprint", () => {
     symlinkSync(real, link)
 
     expect(
-      Object.keys(configFingerprint([join(realpathSync(real), "gtd.config.ts")], link, read)),
+      Object.keys(
+        configFingerprint(
+          nodeSyncIo,
+          inMemPath,
+          [join(realpathSync(real), "gtd.config.ts")],
+          link,
+          read,
+        ),
+      ),
     ).toEqual(["gtd.config.ts"])
   })
 
@@ -58,7 +76,9 @@ describe("the config fingerprint", () => {
     const root = mkdtempSync(join(tmpdir(), "gtd-fingerprint-"))
     writeFileSync(join(root, "a\x1b.ts"), "export const a = 1\n")
 
-    expect(configFingerprint([join(root, "a\x1b.ts")], root, read)).toEqual({})
+    expect(configFingerprint(nodeSyncIo, inMemPath, [join(root, "a\x1b.ts")], root, read)).toEqual(
+      {},
+    )
   })
 
   it("names a file only one side has as changed", () => {

package/src/workflow/fingerprint.ts

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto"
-import { realpathSync } from "node:fs"
-import { relative, sep } from "node:path"
+import type { Path } from "effect"
+import type { SyncIo } from "../platform/index.js"
 
 /** Path (relative to `root`) → content hash of every file a config load touched. */
 export type ConfigFingerprint = Readonly<Record<string, string>>
@@ -12,12 +11,9 @@ const HASH_LENGTH = 16
 // eslint-disable-next-line no-control-regex -- the control range IS the point
 const CONTROL_CHARACTER = /[\x00-\x1f\x7f-\x9f]/
 
-const contentHash = (content: string | Buffer): string =>
-  createHash("sha256").update(content).digest("hex").slice(0, HASH_LENGTH)
-
-const realOr = (path: string): string => {
+const realOr = (io: SyncIo, path: string): string => {
   try {
-    return realpathSync(path)
+    return io.realPath(path)
   } catch {
     return path
   }
@@ -28,17 +24,19 @@ const realOr = (path: string): string => {
 // Paths are real paths: a loader may report `/private/var/…` for a root
 // reached through the `/var` symlink, and the two must still relate.
 export const configFingerprint = (
+  io: SyncIo,
+  paths: Path.Path,
   files: readonly string[],
   root: string,
   read: (path: string) => string | undefined,
 ): ConfigFingerprint => {
   const fingerprint: Record<string, string> = {}
-  const realRoot = realOr(root)
+  const realRoot = realOr(io, root)
   for (const file of files) {
-    const path = relative(realRoot, realOr(file)).split(sep).join("/")
+    const path = paths.relative(realRoot, realOr(io, file)).split(paths.sep).join("/")
     if (CONTROL_CHARACTER.test(path)) continue
     const content = read(file)
-    if (content !== undefined) fingerprint[path] = contentHash(content)
+    if (content !== undefined) fingerprint[path] = io.hash("sha256", content).slice(0, HASH_LENGTH)
   }
   return fingerprint
 }

package/src/workflow/index.ts

@@ -23,7 +23,11 @@ export {
   SETTING_NAME_RULE,
 } from "./vars.js"
 export { resolveScopeAccess, resolveScopeSkills } from "./skills.js"
-export { seededValidateCommand, isSeededValidateCommand } from "./SteeringFormats.js"
+export {
+  declaredValidateCommand,
+  seededValidateCommand,
+  isSeededValidateCommand,
+} from "./SteeringFormats.js"
 export {
   type ChangeStatus,
   type PendingChange,

package/src/workflow/load.test.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync, mkdirSync
 import { join } from "node:path"
 import { tmpdir } from "node:os"
 import { afterEach, beforeEach, describe, expect, it } from "vitest"
-import { Cause, Effect, Exit, Layer } from "effect"
+import { Cause, Effect, Exit, Layer, type Path } from "effect"
 import { Narrator, GitService, Host, Workspace, NodeServices } from "../platform/index.js"
 import {
   ConfigDiscovery,
@@ -23,7 +23,9 @@ type Env = Readonly<Record<string, string>>
 const baseLayer = (dir: string, env: Env = {}) => {
   const hostLayer = Host.layer({ root: dir, home: homeDir, env })
   const gitLayer = GitService.Live.pipe(Layer.provide(Layer.merge(hostLayer, NodeServices.layer)))
-  const workspaceLayer = Workspace.Live.pipe(Layer.provide(Layer.merge(hostLayer, gitLayer)))
+  const workspaceLayer = Workspace.Live.pipe(
+    Layer.provide(Layer.mergeAll(hostLayer, gitLayer, NodeServices.layer)),
+  )
   return Layer.mergeAll(hostLayer, gitLayer, workspaceLayer)
 }
 
@@ -34,18 +36,25 @@ const layer = (dir: string, env: Env = {}) =>
   Layer.mergeAll(
     ConfigService.Live,
     ConfigDiscovery.Live,
-    baseLayer(dir, env),
     Narrator.layer(() => {}, false),
-  )
+  ).pipe(Layer.provideMerge(baseLayer(dir, env)), Layer.provideMerge(NodeServices.layer))
 
 const run = <A>(
-  eff: Effect.Effect<A, Error, ConfigService | ConfigDiscovery | Narrator | Workspace | Host>,
+  eff: Effect.Effect<
+    A,
+    Error,
+    ConfigService | ConfigDiscovery | Narrator | Workspace | Host | Path.Path
+  >,
   dir: string = projectDir,
   env: Env = {},
 ) => Effect.runPromise(eff.pipe(Effect.provide(layer(dir, env))))
 
 const runExit = <A>(
-  eff: Effect.Effect<A, Error, ConfigService | ConfigDiscovery | Narrator | Workspace | Host>,
+  eff: Effect.Effect<
+    A,
+    Error,
+    ConfigService | ConfigDiscovery | Narrator | Workspace | Host | Path.Path
+  >,
   dir: string = projectDir,
 ) => Effect.runPromiseExit(eff.pipe(Effect.provide(layer(dir))))
 
@@ -265,6 +274,7 @@ describe("ConfigService", () => {
             others,
             baseLayer(projectDir),
             Narrator.layer((m) => warnings.push(m), false),
+            NodeServices.layer,
           ),
         ),
       ),