@dreki-gg/pi-plan-mode 0.26.0 → 0.26.1

package/extensions/plan-mode/schema.ts

@@ -1,99 +0,0 @@
-/**
- * Effect Schema definitions for plan-mode persisted records.
- *
- * These replace the hand-rolled type guards. Schemas are the single source of
- * truth for record shape; the mutable TS interfaces in `types.ts` are kept for
- * the imperative orchestration code (which mutates tasks in place) and are
- * structurally compatible with the decoded values.
- */
-
-import { Schema } from 'effect';
-
-export const TaskStatusSchema = Schema.Literal('pending', 'done', 'skipped', 'blocked', 'deferred');
-
-export const TaskOriginSchema = Schema.Literal('plan', 'discovered');
-
-export const TaskRecordSchema = Schema.Struct({
-  _type: Schema.Literal('task'),
-  id: Schema.String,
-  description: Schema.String,
-  details: Schema.optional(Schema.String),
-  status: TaskStatusSchema,
-  origin: Schema.optional(TaskOriginSchema),
-  depends_on: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
-  notes: Schema.optional(Schema.String),
-  created_at: Schema.String,
-  updated_at: Schema.String,
-});
-
-export const TaskMetaSchema = Schema.Struct({
-  _type: Schema.Literal('meta'),
-  title: Schema.String,
-  plan_name: Schema.String,
-  created_at: Schema.String,
-  /** Optional git commit the plan was written against (back-compat: absent on older plans). */
-  base_commit: Schema.optional(Schema.String),
-});
-
-/** A single tasks.jsonl line is either the meta record or a task record. */
-export const TasksLineSchema = Schema.Union(TaskMetaSchema, TaskRecordSchema);
-
-/**
- * Plan lifecycle statuses.
- *   - in-progress: active, tracked, eligible for auto-resolution
- *   - done:        completed (all tasks resolved)
- *   - superseded:  closed because another plan absorbed the work
- *   - abandoned:   closed without shipping (rejected / won't do)
- * Only `in-progress` is treated as active; the rest are terminal.
- */
-export const PlanStatusSchema = Schema.Literal('in-progress', 'done', 'superseded', 'abandoned');
-
-export const PlanManifestEntrySchema = Schema.Struct({
-  _type: Schema.Literal('plan'),
-  name: Schema.String,
-  status: PlanStatusSchema,
-  title: Schema.String,
-  created_at: Schema.String,
-  completed_at: Schema.NullOr(Schema.String),
-  /** Optional human-readable reason, used for terminal statuses. */
-  reason: Schema.optional(Schema.String),
-  /** Parent initiative name (kebab). Absent = standalone flat plan. */
-  initiative: Schema.optional(Schema.String),
-  /**
-   * Plan-level dependencies: names of plans this plan depends on. Distinct from
-   * the task-level `depends_on` above. Cross-initiative references are allowed.
-   */
-  depends_on: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
-});
-
-/**
- * Initiative lifecycle statuses reuse the plan lifecycle literals. An
- * initiative's status is a projection of its member plans' statuses, with the
- * same terminal-guard semantics as plans.
- */
-export const InitiativeStatusSchema = PlanStatusSchema;
-
-export const InitiativeManifestEntrySchema = Schema.Struct({
-  _type: Schema.Literal('initiative'),
-  name: Schema.String,
-  status: InitiativeStatusSchema,
-  title: Schema.String,
-  created_at: Schema.String,
-  completed_at: Schema.NullOr(Schema.String),
-  /** Optional human-readable reason, used for terminal statuses. */
-  reason: Schema.optional(Schema.String),
-});
-
-export const ExecPendingConfigSchema = Schema.Struct({
-  model: Schema.Struct({ provider: Schema.String, id: Schema.String }),
-  thinking: Schema.String,
-});
-
-export const decodeTaskRecord = Schema.decodeUnknownEither(TaskRecordSchema);
-export const decodeTaskMeta = Schema.decodeUnknownEither(TaskMetaSchema);
-export const decodeTasksLine = Schema.decodeUnknownEither(TasksLineSchema);
-export const decodePlanManifestEntry = Schema.decodeUnknownEither(PlanManifestEntrySchema);
-export const decodeInitiativeManifestEntry = Schema.decodeUnknownEither(
-  InitiativeManifestEntrySchema,
-);
-export const decodeExecPendingConfig = Schema.decodeUnknownEither(ExecPendingConfigSchema);

package/extensions/plan-mode/storage/atomic-write.ts

@@ -1,75 +0,0 @@
-import { Effect } from 'effect';
-import { createWriteStream } from 'node:fs';
-import { open, rename, rm } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { PlanWriteError } from '../errors.js';
-
-export interface AtomicWriteOptions {
-  /** Test seam: file mode for the temporary file. */
-  mode?: number;
-}
-
-/**
- * Atomically write `data` to `path`: write to a temp file, fsync, rename into
- * place, then best-effort fsync the directory. Failures surface as
- * `PlanWriteError`.
- */
-export function writeFileAtomic(
-  path: string,
-  data: string | Buffer,
-  options: AtomicWriteOptions = {},
-): Effect.Effect<void, PlanWriteError> {
-  return Effect.tryPromise({
-    try: () => writeFileAtomicPromise(path, data, options),
-    catch: (cause) => new PlanWriteError({ path, cause }),
-  });
-}
-
-async function writeFileAtomicPromise(
-  path: string,
-  data: string | Buffer,
-  options: AtomicWriteOptions,
-): Promise<void> {
-  const dir = dirname(path);
-  const tempPath = join(dir, `.${process.pid}.${randomUUID()}.tmp`);
-  let completed = false;
-
-  try {
-    await writeAndSync(tempPath, data, options.mode);
-    await rename(tempPath, path);
-    completed = true;
-    await syncDirectory(dir);
-  } finally {
-    if (!completed) {
-      await rm(tempPath, { force: true }).catch(() => undefined);
-    }
-  }
-}
-
-async function writeAndSync(path: string, data: string | Buffer, mode?: number): Promise<void> {
-  await new Promise<void>((resolve, reject) => {
-    const stream = createWriteStream(path, { flags: 'wx', mode });
-    stream.once('error', reject);
-    stream.once('finish', resolve);
-    stream.end(data);
-  });
-
-  const handle = await open(path, 'r+');
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-
-async function syncDirectory(dir: string): Promise<void> {
-  // Directory fsync is best-effort: supported on Unix, not always elsewhere.
-  const handle = await open(dir, 'r').catch(() => undefined);
-  if (!handle) return;
-  try {
-    await handle.sync().catch(() => undefined);
-  } finally {
-    await handle.close().catch(() => undefined);
-  }
-}

package/extensions/plan-mode/storage/file-lock.ts

@@ -1,49 +0,0 @@
-/**
- * Process-wide keyed mutex for serializing read-modify-write on shared files.
- *
- * Pi runs every tool call in a single Node process. When several tool calls run
- * in one block (e.g. three `submit_initiative` calls, or concurrent
- * `submit_plan` / `revise_plan`), each does an independent
- * read → modify → write against the same registry file. Without serialization
- * their reads all observe the same starting state and the last write clobbers
- * the rest — a classic lost-update race.
- *
- * `withFileLock` wraps a read-modify-write critical section so only one runs at
- * a time per `key` (the registry path). The semaphore is created eagerly with
- * `unsafeMakeSemaphore` and cached per key, so its permit count lives in plain
- * shared memory and serializes correctly even across independent
- * `Effect.runPromise` invocations (separate tool executes).
- *
- * NOTE: this guards against in-process concurrency only. Atomic writes
- * (`writeFileAtomic`) still protect against torn files from other processes,
- * but cross-process registry coordination is out of scope.
- */
-
-import { Effect } from 'effect';
-
-const locks = new Map<string, Effect.Semaphore>();
-
-function lockFor(key: string): Effect.Semaphore {
-  let lock = locks.get(key);
-  if (!lock) {
-    lock = Effect.unsafeMakeSemaphore(1);
-    locks.set(key, lock);
-  }
-  return lock;
-}
-
-/**
- * Run `effect` while holding the single permit for `key`. Concurrent callers
- * with the same key queue and run one at a time; the permit is always released,
- * even on failure or interruption.
- *
- * Do NOT nest `withFileLock` for the same key inside another — the permit is
- * not reentrant and would deadlock. Express composite read-modify-write as one
- * locked section instead.
- */
-export function withFileLock<A, E, R>(
-  key: string,
-  effect: Effect.Effect<A, E, R>,
-): Effect.Effect<A, E, R> {
-  return Effect.suspend(() => lockFor(key).withPermits(1)(effect));
-}

package/extensions/plan-mode/storage/initiatives-manifest.ts

@@ -1,154 +0,0 @@
-/**
- * `.plans/initiatives.jsonl` registry — the initiative-level sibling of
- * `plans-manifest.ts`.
- *
- * An initiative groups multiple plans. Its `status` is a PROJECTION of its
- * member plans' statuses (see `reconcileInitiativeStatus` in `../initiative.ts`
- * for the projection wiring): `done` when every member plan is terminal,
- * `in-progress` otherwise. Manually-set terminal statuses (`superseded` /
- * `abandoned` via `update_initiative`) are never auto-overridden.
- *
- * This module is intentionally dependency-light: it knows how to read/write the
- * registry. The projection (which must read the PLANS manifest) lives in
- * `../initiative.ts` to keep the dependency direction one-way and cycle-free.
- */
-
-import { Effect, Either, Option } from 'effect';
-import { FileSystem } from '../effects/filesystem.js';
-import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
-import { decodeInitiativeManifestEntry } from '../schema.js';
-import type { InitiativeStatus } from '../types.js';
-import { withFileLock } from './file-lock.js';
-
-const MANIFEST_DIR = '.plans';
-const MANIFEST_PATH = '.plans/initiatives.jsonl';
-
-export interface InitiativeManifestEntry {
-  _type: 'initiative';
-  name: string;
-  status: InitiativeStatus;
-  title: string;
-  created_at: string;
-  completed_at: string | null;
-  reason?: string;
-}
-
-/** A status is terminal (closed) when it is anything other than in-progress. */
-export function isTerminalStatus(status: InitiativeStatus): boolean {
-  return status !== 'in-progress';
-}
-
-type ReadError = JsonlParseError | JsonlValidationError;
-
-export function readInitiativesManifest(): Effect.Effect<
-  InitiativeManifestEntry[],
-  ReadError,
-  FileSystem
-> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    // A missing or unreadable manifest is treated as "no initiatives".
-    const maybeText = yield* Effect.option(fs.readFileString(MANIFEST_PATH));
-    if (Option.isNone(maybeText)) return [];
-
-    const entries: InitiativeManifestEntry[] = [];
-    for (const [index, raw] of maybeText.value.split(/\r?\n/).entries()) {
-      if (!raw.trim()) continue;
-      const line = index + 1;
-
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(raw);
-      } catch (cause) {
-        return yield* Effect.fail(new JsonlParseError({ path: MANIFEST_PATH, line, cause }));
-      }
-
-      const decoded = decodeInitiativeManifestEntry(parsed);
-      if (Either.isLeft(decoded)) {
-        return yield* Effect.fail(
-          new JsonlValidationError({ path: MANIFEST_PATH, line, reason: decoded.left.message }),
-        );
-      }
-      entries.push(decoded.right);
-    }
-    return entries;
-  });
-}
-
-export function writeInitiativesManifest(
-  entries: InitiativeManifestEntry[],
-): Effect.Effect<void, PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    yield* fs.makeDir(MANIFEST_DIR);
-    const content =
-      entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
-    yield* fs.writeFileAtomic(MANIFEST_PATH, content);
-  });
-}
-
-export interface InitiativeUpsert {
-  status: InitiativeStatus;
-  title?: string;
-  reason?: string;
-}
-
-/**
- * Pure transform: upsert `name` into the in-memory `entries` array, preserving
- * created_at from any existing entry. No IO — shared by the locked
- * `upsertInitiativeEntry` and `reconcileInitiativeStatus` so both flow through
- * one serialized read-modify-write and never nest locks.
- */
-export function applyInitiativeUpsert(
-  entries: InitiativeManifestEntry[],
-  name: string,
-  updates: InitiativeUpsert,
-): void {
-  const now = new Date().toISOString();
-  const index = entries.findIndex((entry) => entry.name === name);
-  const existing = index === -1 ? undefined : entries[index];
-  const entry: InitiativeManifestEntry = {
-    _type: 'initiative',
-    name,
-    status: updates.status,
-    title: updates.title ?? existing?.title ?? 'Untitled initiative',
-    created_at: existing?.created_at ?? now,
-    // Terminal statuses record a completion timestamp; reopening clears it.
-    completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
-    reason: updates.reason ?? existing?.reason,
-  };
-  if (index === -1) entries.push(entry);
-  else entries[index] = entry;
-}
-
-/**
- * Serialized read-modify-write of the initiatives registry. Holds a
- * process-wide lock on the manifest path across the whole read → transform →
- * write so concurrent tool calls cannot clobber each other. `transform` may run
- * IO (e.g. read the plans manifest to project status) and mutates the entries
- * array in place, returning `true` when it changed something.
- */
-export function mutateInitiativesManifest<E, R>(
-  transform: (entries: InitiativeManifestEntry[]) => Effect.Effect<boolean, E, R>,
-): Effect.Effect<void, ReadError | PlanWriteError | E, FileSystem | R> {
-  return withFileLock(
-    MANIFEST_PATH,
-    Effect.gen(function* () {
-      const entries = yield* readInitiativesManifest();
-      const changed = yield* transform(entries);
-      if (changed) yield* writeInitiativesManifest(entries);
-    }),
-  );
-}
-
-export function upsertInitiativeEntry(
-  name: string,
-  updates: InitiativeUpsert,
-): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return mutateInitiativesManifest((entries) =>
-    Effect.sync(() => {
-      applyInitiativeUpsert(entries, name, updates);
-      return true;
-    }),
-  );
-}

package/extensions/plan-mode/storage/plan-storage.ts

@@ -1,88 +0,0 @@
-/**
- * Plan disk I/O — exec-pending markers and handoff documents.
- */
-
-import { Effect, Either, Option } from 'effect';
-import { FileSystem } from '../effects/filesystem.js';
-import type { PlanWriteError } from '../errors.js';
-import { decodeExecPendingConfig } from '../schema.js';
-import type { ExecPendingConfig } from '../types.js';
-import { EXEC_PENDING_FILE } from '../constants.js';
-
-const PLANS_DIR = '.plans';
-
-export function writeExecPending(
-  dir: string,
-  config: ExecPendingConfig,
-): Effect.Effect<void, PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    yield* fs.makeDir(dir);
-    yield* fs.writeFileString(
-      `${dir}/${EXEC_PENDING_FILE}`,
-      JSON.stringify(config, null, 2) + '\n',
-    );
-  });
-}
-
-export function readAndClearExecPending(): Effect.Effect<
-  { planDir: string; config: ExecPendingConfig } | undefined,
-  never,
-  FileSystem
-> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    const maybeDirs = yield* Effect.option(fs.listDirectories(PLANS_DIR));
-    if (Option.isNone(maybeDirs)) return undefined;
-
-    for (const name of maybeDirs.value) {
-      const dir = `${PLANS_DIR}/${name}`;
-      const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
-      const maybeText = yield* Effect.option(fs.readFileString(markerPath));
-      if (Option.isNone(maybeText)) continue;
-
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(maybeText.value);
-      } catch {
-        continue;
-      }
-      const decoded = decodeExecPendingConfig(parsed);
-      if (Either.isLeft(decoded)) continue;
-
-      yield* Effect.ignore(fs.removeFile(markerPath));
-      return { planDir: dir, config: decoded.right };
-    }
-    return undefined;
-  });
-}
-
-export function saveHandoff(
-  planDir: string,
-  content: string,
-): Effect.Effect<void, PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    yield* fs.makeDir(planDir);
-    yield* fs.writeFileString(`${planDir}/HANDOFF.md`, content);
-  });
-}
-
-export function loadHandoff(planDir: string): Effect.Effect<string | undefined, never, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    const maybeText = yield* Effect.option(fs.readFileString(`${planDir}/HANDOFF.md`));
-    return Option.getOrUndefined(maybeText);
-  });
-}
-
-export function saveInitiative(
-  initiativeDir: string,
-  content: string,
-): Effect.Effect<void, PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    yield* fs.makeDir(initiativeDir);
-    yield* fs.writeFileString(`${initiativeDir}/INITIATIVE.md`, content);
-  });
-}

package/extensions/plan-mode/storage/plans-manifest.ts

@@ -1,174 +0,0 @@
-import { Effect, Either, Option } from 'effect';
-import { FileSystem } from '../effects/filesystem.js';
-import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
-import { decodePlanManifestEntry } from '../schema.js';
-import type { PlanStatus } from '../types.js';
-import { withFileLock } from './file-lock.js';
-
-const MANIFEST_DIR = '.plans';
-const MANIFEST_PATH = '.plans/plans.jsonl';
-
-export interface PlanManifestEntry {
-  _type: 'plan';
-  name: string;
-  status: PlanStatus;
-  title: string;
-  created_at: string;
-  completed_at: string | null;
-  reason?: string;
-  /** Parent initiative name (kebab). Absent = standalone flat plan. */
-  initiative?: string;
-  /** Plan-level dependencies (plan names). Cross-initiative allowed. */
-  depends_on?: string[];
-}
-
-/** A status is terminal (closed) when it is anything other than in-progress. */
-export function isTerminalStatus(status: PlanStatus): boolean {
-  return status !== 'in-progress';
-}
-
-type ReadError = JsonlParseError | JsonlValidationError;
-
-export function readPlansManifest(): Effect.Effect<PlanManifestEntry[], ReadError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    // A missing or unreadable manifest is treated as "no plans".
-    const maybeText = yield* Effect.option(fs.readFileString(MANIFEST_PATH));
-    if (Option.isNone(maybeText)) return [];
-
-    const entries: PlanManifestEntry[] = [];
-    for (const [index, raw] of maybeText.value.split(/\r?\n/).entries()) {
-      if (!raw.trim()) continue;
-      const line = index + 1;
-
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(raw);
-      } catch (cause) {
-        return yield* Effect.fail(new JsonlParseError({ path: MANIFEST_PATH, line, cause }));
-      }
-
-      const decoded = decodePlanManifestEntry(parsed);
-      if (Either.isLeft(decoded)) {
-        return yield* Effect.fail(
-          new JsonlValidationError({ path: MANIFEST_PATH, line, reason: decoded.left.message }),
-        );
-      }
-      entries.push(decoded.right);
-    }
-    return entries;
-  });
-}
-
-export function writePlansManifest(
-  entries: PlanManifestEntry[],
-): Effect.Effect<void, PlanWriteError, FileSystem> {
-  return Effect.gen(function* () {
-    const fs = yield* FileSystem;
-    yield* fs.makeDir(MANIFEST_DIR);
-    const content =
-      entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
-    yield* fs.writeFileAtomic(MANIFEST_PATH, content);
-  });
-}
-
-export interface PlanUpsert {
-  status: PlanStatus;
-  title?: string;
-  reason?: string;
-  /** Parent initiative name; preserved when omitted. */
-  initiative?: string;
-  /** Plan-level dependencies (plan names); preserved when omitted. */
-  depends_on?: string[];
-}
-
-/**
- * Pure transform: upsert `name` into the in-memory `entries` array, preserving
- * created_at / membership / deps from any existing entry. No IO — shared by the
- * locked `upsertPlanEntry` and `reconcilePlanStatus` so both flow through one
- * serialized read-modify-write and never nest locks.
- */
-export function applyPlanUpsert(
-  entries: PlanManifestEntry[],
-  name: string,
-  updates: PlanUpsert,
-): void {
-  const now = new Date().toISOString();
-  const index = entries.findIndex((entry) => entry.name === name);
-  const existing = index === -1 ? undefined : entries[index];
-  const entry: PlanManifestEntry = {
-    _type: 'plan',
-    name,
-    status: updates.status,
-    title: updates.title ?? existing?.title ?? 'Untitled plan',
-    created_at: existing?.created_at ?? now,
-    // Terminal statuses record a completion timestamp; reopening clears it.
-    completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
-    reason: updates.reason ?? existing?.reason,
-    // Membership + plan-level deps are preserved across status-only upserts.
-    initiative: updates.initiative ?? existing?.initiative,
-    depends_on: updates.depends_on ?? existing?.depends_on,
-  };
-  if (index === -1) entries.push(entry);
-  else entries[index] = entry;
-}
-
-/**
- * Serialized read-modify-write of the plans registry. Holds a process-wide lock
- * on the manifest path across the whole read → transform → write so concurrent
- * tool calls cannot clobber each other (lost-update race). `transform` mutates
- * the entries array in place and returns `true` when it changed something
- * (return `false` to skip the rewrite).
- */
-export function mutatePlansManifest(
-  transform: (entries: PlanManifestEntry[]) => boolean,
-): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return withFileLock(
-    MANIFEST_PATH,
-    Effect.gen(function* () {
-      const entries = yield* readPlansManifest();
-      const changed = transform(entries);
-      if (changed) yield* writePlansManifest(entries);
-    }),
-  );
-}
-
-export function upsertPlanEntry(
-  name: string,
-  updates: PlanUpsert,
-): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return mutatePlansManifest((entries) => {
-    applyPlanUpsert(entries, name, updates);
-    return true;
-  });
-}
-
-/**
- * Reconcile a plan's registry status from its task state.
- *
- * The registry `status` is a PROJECTION of task state, not a parallel flag.
- * Call this wherever tasks are written so completion is never coupled to a
- * formal in-session execution run (see FEEDBACK #1). `finalizable` means every
- * active task is resolved AND no deferred follow-ups remain.
- *
- * Guard: a manually-set terminal status (`superseded` / `abandoned`) is never
- * auto-overridden — only `in-progress` ⇄ `done` is derived from tasks.
- */
-export function reconcilePlanStatus(
-  name: string,
-  finalizable: boolean,
-  title?: string,
-): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
-  return mutatePlansManifest((entries) => {
-    const existing = entries.find((entry) => entry.name === name);
-    // Reconcile only reflects task state for KNOWN plans; never conjure an
-    // entry for an unregistered plan (orphans are surfaced, not auto-created).
-    if (!existing) return false;
-    // Do not resurrect / clobber an explicitly closed plan.
-    if (existing.status === 'superseded' || existing.status === 'abandoned') return false;
-    const status: PlanStatus = finalizable ? 'done' : 'in-progress';
-    if (existing.status === status) return false; // no change
-    applyPlanUpsert(entries, name, { status, title });
-    return true;
-  });
-}