@naswerks/periscope 1.0.0 → 1.0.1

package/src/workspace/plain-dir.ts

@@ -0,0 +1,132 @@
+/**
+ * One plain directory per session, under a root the embedder names.
+ *
+ * The simplest thing that satisfies the contract, and enough to prove an agent works: no git, no
+ * branches, no conventions. A code-review tool that clones somewhere itself, or a host running
+ * agents over scratch space, wants exactly this and nothing more.
+ *
+ * Isolation is by construction, not by check. Each session's directory is a distinct child of the
+ * root named by its own id, so two sessions cannot share one unless they share an id — and ids are
+ * refused if they contain separators, which is the only way one could climb into another's.
+ */
+import type { Result } from '../core/result.js';
+import { ok, refuse } from '../core/result.js';
+import { isAbsolutePath, normalizePath } from '../core/paths.js';
+import type {
+  ReleaseOptions,
+  ReleaseReceipt,
+  Workspace,
+  WorkspaceEffects,
+  WorkspaceEntry,
+  WorkspaceInventory,
+  WorkspaceProvider,
+} from './provider.js';
+import { keyDirectlyUnder, rejectUnusableId } from './git-worktree.js';
+
+export interface PlainDirProviderOptions {
+  /** Absolute. Every session directory is created directly beneath it. */
+  readonly root: string;
+  readonly effects: WorkspaceEffects;
+}
+
+export class PlainDirProvider implements WorkspaceProvider {
+  readonly #root: string;
+  readonly #effects: WorkspaceEffects;
+
+  constructor(options: PlainDirProviderOptions) {
+    this.#root = normalizePath(options.root);
+    this.#effects = options.effects;
+  }
+
+  /** Where this session's directory is, whether or not it exists yet. */
+  pathFor(sessionId: string): string {
+    return `${this.#root}/${sessionId}`;
+  }
+
+  /**
+   * The directories under the root. A plain directory has no branch, so every git-shaped member is
+   * null or false, and `merged` is null: nothing here can say whether work is kept anywhere.
+   */
+  async inventory(): Promise<Result<WorkspaceInventory>> {
+    const list = this.#effects.listDirectories?.bind(this.#effects);
+    if (list === undefined) {
+      return refuse<WorkspaceInventory>(
+        'workspace-list-failed',
+        'this provider has no directory listing to read',
+      );
+    }
+    try {
+      const names = await list(this.#root);
+      const entries: WorkspaceEntry[] = names.map((name) => ({
+        key: name,
+        path: `${this.#root}/${name}`,
+        branch: null,
+        head: null,
+        detached: false,
+        locked: false,
+        prunable: false,
+        merged: null,
+        aheadCount: null,
+        lastCommitAt: null,
+      }));
+      return ok({ entries, defaultBranch: null });
+    } catch (error) {
+      return refuse<WorkspaceInventory>('workspace-list-failed', describe(error));
+    }
+  }
+
+  async provision(sessionId: string): Promise<Result<Workspace>> {
+    const invalid = rejectUnusableId<Workspace>(sessionId);
+    if (invalid !== null) return invalid;
+    if (!isAbsolutePath(this.#root)) {
+      return refuse<Workspace>(
+        'workspace-provision-failed',
+        `the workspace root must be absolute: ${this.#root}`,
+      );
+    }
+
+    const path = this.pathFor(sessionId);
+    try {
+      // Creating an existing directory is a no-op, so re-provisioning attaches to whatever is there
+      // rather than replacing it. Same rule as the worktree provider, for the same reason: a host
+      // that lost track of a directory must not destroy its contents on the way back.
+      const reused = await this.#effects.exists(path);
+      await this.#effects.makeDirectory(path);
+      return ok({ path, meta: { attached: reused ? 'directory' : 'created' } });
+    } catch (error) {
+      return refuse<Workspace>(
+        'workspace-provision-failed',
+        `could not provision a directory for ${sessionId} at ${path}: ${describe(error)}`,
+      );
+    }
+  }
+
+  /** The key of the directory at `path` when it sits directly under the root, else null. */
+  keyForPath(path: string): string | null {
+    return keyDirectlyUnder(path, this.#root);
+  }
+
+  async release(sessionId: string, options?: ReleaseOptions): Promise<Result<ReleaseReceipt | undefined>> {
+    // The default is to leave it — see ReleaseOptions. A directory nobody asked to remove is
+    // evidence, and deleting it by default destroys it exactly when a session ended badly.
+    if (options?.remove !== true) return ok(undefined);
+
+    // A plain directory has no branch, so `deleteBranch` finds nothing to delete: the receipt says
+    // so (`branchDeleted: false`, no refusal), the idempotent answer for a thing already absent.
+    const path = this.pathFor(sessionId);
+    try {
+      const existed = await this.#effects.exists(path);
+      if (existed) await this.#effects.removeDirectory(path);
+      return ok({ path, directoryRemoved: existed, branchDeleted: false, refusal: null });
+    } catch (error) {
+      return refuse<ReleaseReceipt>(
+        'workspace-release-failed',
+        `could not release the directory for ${sessionId} at ${path}: ${describe(error)}`,
+      );
+    }
+  }
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/workspace/provider.ts

@@ -0,0 +1,159 @@
+/**
+ * The directory a session runs in, and who decides what it looks like.
+ *
+ * This is entirely the host's job. The SDK has no provisioning surface at all — it takes a `cwd`
+ * and assumes something already made it. So the choice of what a workspace is — a plain directory, a
+ * checkout, a linked worktree, a container mount — is the embedder's, and this is the seam where
+ * that choice plugs in.
+ *
+ * The provider is the embedder's, not the package's. Two implementations ship because they cover
+ * the two shapes almost everyone needs, but the interesting policies are not here and must not move
+ * here: a shared directory per task, a write-once key, a branch naming rule, a cleanup schedule.
+ * Those are the embedder's own conventions, and a tool that reviews code in a throwaway clone
+ * should be able to write its own provider without ever learning that any of them exist.
+ *
+ * Every result is a named refusal, never an exception. `provision` failing is an ordinary outcome
+ * — a disk is full, a path is taken, a git command failed — and the caller has to decide what to do
+ * about it. A thrown error at this seam would make "the session could not get a directory"
+ * indistinguishable from a bug in the provider, and the package names the difference everywhere else.
+ */
+import type { Result } from '../core/result.js';
+import type { Refusal } from '../core/refusal.js';
+
+/** Where a session works, plus whatever the provider wants the caller to know about it. */
+export interface Workspace {
+  /** Absolute, always. This is what becomes the session's `cwd`. */
+  readonly path: string;
+  /**
+   * Provider-specific facts, as strings.
+   *
+   * Deliberately opaque to this package. A git provider reports its branch and base ref here; a
+   * plain-directory provider reports almost nothing; somebody else's reports a container id. Nothing
+   * in the host reads a key out of this — it exists so a provider can tell its caller something
+   * without this file having to grow a field for every provider anyone might write.
+   */
+  readonly meta: Readonly<Record<string, string>>;
+}
+
+/** What `release` should do with the directory. */
+export interface ReleaseOptions {
+  /**
+   * Remove the workspace from disk. Defaults to false.
+   *
+   * The default is "leave it", and that is a deliberate asymmetry. A session that ended badly is
+   * one whose directory somebody wants to look at, and a host that tidied up by default would
+   * destroy the evidence exactly when it matters. Leaving a directory costs disk; deleting one that
+   * was still wanted costs the investigation.
+   */
+  readonly remove?: boolean;
+  /**
+   * Delete the branch the worktree is on, after the directory. Defaults to false, and only means
+   * anything with `remove`. Deleting a branch is not reversible the way removing a directory is,
+   * so it is asked for per call and never remembered.
+   */
+  readonly deleteBranch?: boolean;
+  /** Delete the branch even when it is not merged into the repository's default branch. */
+  readonly force?: boolean;
+}
+
+/**
+ * What a release did. `refusal` is the partial: the directory went and the branch did not, said
+ * rather than hidden. Null means everything asked for happened, or was already absent.
+ */
+export interface ReleaseReceipt {
+  /** The workspace's path as this provider knows it. */
+  readonly path: string;
+  /** A directory existed and is gone. */
+  readonly directoryRemoved: boolean;
+  readonly branchDeleted: boolean;
+  readonly refusal: Refusal | null;
+}
+
+/** One workspace on disk, as the provider's inventory reports it. See `WorkspaceListEntry` on the wire. */
+export interface WorkspaceEntry {
+  readonly key: string;
+  readonly path: string;
+  readonly branch: string | null;
+  readonly head: string | null;
+  readonly detached: boolean;
+  readonly locked: boolean;
+  readonly prunable: boolean;
+  readonly merged: boolean | null;
+  /** Commits past the default branch; null when detached or when no default branch was named. */
+  readonly aheadCount: number | null;
+  readonly lastCommitAt: string | null;
+}
+
+/** What `inventory` answers: every workspace under the root, and the default branch `merged` was judged against. */
+export interface WorkspaceInventory {
+  readonly entries: readonly WorkspaceEntry[];
+  readonly defaultBranch: string | null;
+}
+
+export interface WorkspaceProvider {
+  /**
+   * Get the directory for this session, creating it if needed.
+   *
+   * It must be safe to call twice for one session. A host that lost a directory — a cleanup ran,
+   * a volume remounted, a container restarted — re-provisions, and the second call must attach to
+   * whatever survived rather than recreate it. That is not a nicety: see git-worktree.ts, where
+   * getting it wrong destroys committed work.
+   */
+  provision(sessionId: string): Promise<Result<Workspace>>;
+  /**
+   * Done with it. Idempotent: releasing a session this provider does not hold succeeds. The
+   * receipt is optional so a provider that predates it still conforms; the host reads no receipt as
+   * "vouches for nothing" and reports both flags false.
+   */
+  release(sessionId: string, options?: ReleaseOptions): Promise<Result<ReleaseReceipt | undefined>>;
+  /**
+   * The key of the workspace at `path`, when `path` is a directory directly under this provider's
+   * root; null for anything else. Optional: a provider without it cannot be addressed by path.
+   */
+  keyForPath?(path: string): string | null;
+  /**
+   * What exists under the workspace root right now, read from disk on demand. Optional: a provider
+   * that keeps no inventory leaves it out and the host answers `workspace-list-failed` by name.
+   * Only what this provider provisioned is listed; the repository it links from never is.
+   */
+  inventory?(): Promise<Result<WorkspaceInventory>>;
+  /**
+   * The repository this provider clones from, when it has one. The one directory a controller may
+   * name and get, provider or not: the operator's own checkout has no isolation to protect.
+   */
+  readonly repositoryRoot?: string;
+}
+
+/**
+ * The filesystem and process effects a provider needs, as injected functions.
+ *
+ * Why this exists rather than a direct `node:fs` import. `src/host/` is the only directory allowed
+ * to touch the machine (pinned by pins/host-boundary.test.ts), and the provider logic — which argv a
+ * git call gets, when a directory is reused rather than made, what a release does — is exactly the
+ * part worth testing without a disk. So the logic lives here and the real implementations live in
+ * host/workspace-fs.ts, the same split the path jail already uses.
+ *
+ * The payoff is not tidiness: it makes "never hard-reset an existing branch" a pure unit test rather
+ * than something only a destroyed branch could have proven.
+ */
+export interface WorkspaceEffects {
+  /** Create a directory and every missing parent. Succeeds if it already exists. */
+  makeDirectory(path: string): Promise<void>;
+  /** Does anything exist at this path? */
+  exists(path: string): Promise<boolean>;
+  /** Remove a directory and everything under it. Succeeds if it is already gone. */
+  removeDirectory(path: string): Promise<void>;
+  /** The names of the directories directly under `path`, or an empty list when it does not exist. Optional. */
+  listDirectories?(path: string): Promise<string[]>;
+}
+
+/** Running a command. Separate from the filesystem effects because only one provider needs it. */
+export interface CommandEffects {
+  /**
+   * Run a program with an argv array and return its stdout, trimmed.
+   *
+   * Argv, never a command string. A shell string would make every branch name and path an
+   * injection site, and branch names come from a caller this package does not control.
+   */
+  run(program: string, args: readonly string[], cwd: string): Promise<string>;
+}

package/src/workspace/worktree-porcelain.ts

@@ -0,0 +1,118 @@
+/**
+ * Readers for the three git outputs an inventory is built from. Pure: text in, records out, no
+ * process and no filesystem, so the parsing is testable against fixtures and the provider that
+ * runs the commands stays thin.
+ *
+ * `git worktree list --porcelain` prints one block per worktree, blank-line separated, each line
+ * `<attribute> <value>` or a bare attribute: `worktree <path>`, `HEAD <sha>`, `branch <ref>`,
+ * `detached`, `locked [reason]`, `prunable [reason]`, `bare`. Attributes this reader does not know
+ * are carried past, never fatal, so a newer git cannot break the inventory by adding one.
+ */
+
+/** One worktree as git reports it. `branch` is the short name (`refs/heads/` stripped), null when detached. */
+export interface PorcelainWorktree {
+  readonly path: string;
+  readonly head: string | null;
+  readonly branch: string | null;
+  readonly detached: boolean;
+  readonly locked: boolean;
+  readonly prunable: boolean;
+  readonly bare: boolean;
+}
+
+const HEADS_PREFIX = 'refs/heads/';
+
+export function parseWorktreePorcelain(text: string): PorcelainWorktree[] {
+  const worktrees: PorcelainWorktree[] = [];
+  let current: {
+    path: string;
+    head: string | null;
+    branch: string | null;
+    detached: boolean;
+    locked: boolean;
+    prunable: boolean;
+    bare: boolean;
+  } | null = null;
+
+  const flush = (): void => {
+    if (current !== null) worktrees.push({ ...current });
+    current = null;
+  };
+
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    if (line === '') {
+      flush();
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const attribute = space === -1 ? line : line.slice(0, space);
+    const value = space === -1 ? '' : line.slice(space + 1);
+    if (attribute === 'worktree') {
+      flush();
+      current = {
+        path: value,
+        head: null,
+        branch: null,
+        detached: false,
+        locked: false,
+        prunable: false,
+        bare: false,
+      };
+      continue;
+    }
+    if (current === null) continue;
+    switch (attribute) {
+      case 'HEAD':
+        current.head = value === '' ? null : value;
+        break;
+      case 'branch':
+        current.branch = value.startsWith(HEADS_PREFIX) ? value.slice(HEADS_PREFIX.length) : value;
+        break;
+      case 'detached':
+        current.detached = true;
+        break;
+      case 'locked':
+        current.locked = true;
+        break;
+      case 'prunable':
+        current.prunable = true;
+        break;
+      case 'bare':
+        current.bare = true;
+        break;
+      default:
+        break;
+    }
+  }
+  flush();
+  return worktrees;
+}
+
+/**
+ * `git for-each-ref --format='%(refname:short)%09%(committerdate:iso-strict)' refs/heads/`: one
+ * branch per line, tab-separated. Returns the tip's committer date per branch, as given.
+ */
+export function parseBranchTips(text: string): Map<string, string> {
+  const tips = new Map<string, string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === '') continue;
+    const tab = line.indexOf('\t');
+    if (tab === -1) continue;
+    const branch = line.slice(0, tab).trim();
+    const at = line.slice(tab + 1).trim();
+    if (branch !== '' && at !== '') tips.set(branch, at);
+  }
+  return tips;
+}
+
+/** `git branch --merged <ref> --format='%(refname:short)'`: one branch per line. */
+export function parseBranchList(text: string): Set<string> {
+  const branches = new Set<string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim().replace(/^[*+]\s+/, '');
+    if (line !== '') branches.add(line);
+  }
+  return branches;
+}