fixo-cli 1.0.0

package/dist/runtime/staging.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Atomic Workspace Shadow Staging — Pillar 2 of the Phase 2 safety
+ * refactor. The problem: a direct `fs.writeFileSync` to a user's
+ * source file is a non-atomic, non-rollbackable operation. If the
+ * process is killed mid-write, the user is left with a partially
+ * truncated file. If a downstream validation step fails, the
+ * user is left with a corrupted file. Both outcomes are
+ * unacceptable for a tool that markets itself as "enterprise
+ * safe".
+ *
+ * The fix: route every file write through a `.fixo/staging/`
+ * shadow directory, validate it (Pillar 3 LSP gate will plug in
+ * here), and only then perform an atomic `fs.renameSync` swap.
+ * If anything goes wrong, restore the original from a sibling
+ * `.pending.bak` file and the user is none the wiser.
+ *
+ * Layout under `cwd`:
+ *
+ *   .fixo/staging/<run-id>/
+ *     <sha256(targetPath)>.pending       # staged content
+ *     <sha256(targetPath)>.meta.json     # { targetPath, mode, createdAt }
+ *
+ *   <targetPath>.pending.bak             # temporary backup, only
+ *                                        # present during commit()
+ *
+ * The staging directory is created with mode `0o700`. Pending
+ * files and their metadata are written with mode `0o600`.
+ *
+ * The manager is synchronous (writes are small, no streaming),
+ * safe to construct at the start of a run, and thread-agnostic —
+ * the run-id is the only thing that disambiguates concurrent
+ * runs against the same workspace.
+ */
+/** Options for {@link AtomicStagingManager}. */
+export interface AtomicStagingOptions {
+    /** Maximum age of a staged write before it is eligible for GC (ms). */
+    ttlMs?: number;
+    /**
+     * If supplied, the callback runs immediately before the rename
+     * swap inside `commit()`. If it throws, the staged write is
+     * rolled back and the original target is preserved. Pillar 3
+     * (LSP pre-save gate) wires in here.
+     */
+    preCommitHook?: (entry: StagedWrite) => Promise<void> | void;
+    /**
+     * Pillar 5 / Protection 3 — structural syntax health check.
+     *
+     * If supplied, the callback runs *after* `preCommitHook` and
+     * *before* the rename swap. It receives the staged content and
+     * the target path, and should throw a {@link StructuralSyntaxError}
+     * (or any `Error`) if the content is unparseable. Pillar 5 wires
+     * in a JavaScript / TypeScript parser here so that catastrophic
+     * syntax damage (e.g. the LLM pasting code into the wrong
+     * function) is caught before it lands on disk.
+     */
+    syntaxHealthCheck?: (entry: StagedWrite, content: string) => Promise<void> | void;
+    /**
+     * If false, the manager operates in "dry-run" mode: stage()
+     * writes to the shadow dir but commit() refuses to swap. Useful
+     * for tests and for users who want the staging guarantees
+     * without the actual file replacement. Defaults to true.
+     */
+    enabled?: boolean;
+}
+/** A staged write, returned by {@link AtomicStagingManager.stage}. */
+export interface StagedWrite {
+    /** Opaque identifier — sha256 of the target path. */
+    readonly id: string;
+    /** Absolute path of the file that will be replaced at commit. */
+    readonly targetPath: string;
+    /** Absolute path of the pending staged file. */
+    readonly pendingPath: string;
+    /** Absolute path of the sidecar metadata file. */
+    readonly metaPath: string;
+    /** When the stage was created (ms since epoch). */
+    readonly createdAt: number;
+    /** Mode the file will have on disk after commit. */
+    readonly mode: number;
+}
+/** Result of {@link AtomicStagingManager.commit}. */
+export interface CommitResult {
+    /** True if the swap succeeded and the file is on disk. */
+    readonly committed: boolean;
+    /** Path that was committed. */
+    readonly targetPath: string;
+    /** Whether a backup of the original was created and cleared. */
+    readonly backupCreated: boolean;
+    /** Number of bytes written to the target. */
+    readonly bytesWritten: number;
+    /** ISO timestamp of the commit. */
+    readonly committedAt: string;
+}
+/** Thrown when a requested staged write does not exist. */
+export declare class StagedWriteNotFoundError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+/** Thrown when commit() rolls back due to a pre-commit hook failure. */
+export declare class PreCommitHookRejectedError extends Error {
+    readonly id: string;
+    readonly cause: unknown;
+    constructor(id: string, cause: unknown);
+}
+/** Thrown when a target path escapes the workspace root. */
+export declare class StagingPathEscapeError extends Error {
+    readonly attempted: string;
+    constructor(attempted: string);
+}
+export declare class AtomicStagingManager {
+    readonly cwd: string;
+    readonly runId: string;
+    readonly options: Required<Pick<AtomicStagingOptions, 'ttlMs' | 'enabled'>> & Pick<AtomicStagingOptions, 'preCommitHook' | 'syntaxHealthCheck'>;
+    /** Absolute path of the staging directory for this run. */
+    readonly stagingDir: string;
+    constructor(cwd: string, runId: string, options?: AtomicStagingOptions);
+    /** Ensure the staging directory exists with mode 0o700. */
+    private ensureStagingDir;
+    /** Reject paths that escape the workspace root. */
+    private resolveTarget;
+    /**
+     * Stage a file for atomic write. Writes the content to
+     * `<staging>/<sha256(target)>.pending` and a sidecar
+     * `<staging>/<sha256(target)>.meta.json` containing the target
+     * path, mode, and timestamp. Returns the staged write metadata.
+     */
+    stage(target: string, content: string, mode?: number): StagedWrite;
+    /** Read a staged write's content (lazy — only read on demand). */
+    read(id: string): string;
+    /** Look up a staged write by id without touching the file system further. */
+    readEntry(id: string): StagedWrite;
+    /** List all staged writes for this run. */
+    list(): StagedWrite[];
+    /**
+     * Remove a staged write without touching the target. Used by the
+     * LSP pre-save gate when it rejects a write.
+     */
+    discard(id: string): void;
+    /**
+     * Commit a staged write to its target path. The flow is:
+     *
+     *   1. Run the optional pre-commit hook (Pillar 3 plugs in here).
+     *   2. Ensure the parent directory of the target exists.
+     *   3. If the target exists, rename it to `<target>.pending.bak`.
+     *   4. Rename the pending file to the target.
+     *   5. Delete the backup.
+     *
+     * If any step fails, the backup (if any) is restored to the
+     * target and the backup itself is removed. The pending and
+     * metadata files are always cleaned up on success.
+     */
+    commit(id: string): Promise<CommitResult>;
+    /**
+     * Apply a surgical in-place edit to an existing file. The new
+     * content is staged under the same `.fixo/staging/<runId>/<id>.pending`
+     * layout and the commit step mirrors `commit()`: backup the
+     * target, atomic rename, clear the backup, clear the meta.
+     *
+     * This is functionally `stage() + commit()` collapsed into a
+     * single call, but the on-disk layout, backup semantics, and
+     * rollback path are identical. Provided so `str_replace` (and
+     * future surgical-edit tools) can route their edits through the
+     * same atomic staging pipeline as `write_file` without touching
+     * the existing `stage()` / `commit()` flow.
+     *
+     * The optional `meta` argument is recorded into `.meta.json` so
+     * the audit trail records the originator of the edit (e.g. a
+     * `str_replace` tool call vs. a `subagent`). The method never
+     * weakens the Pillar 2 atomicity guarantee: if the rename
+     * swap fails, the backup is restored and the original file is
+     * preserved byte-for-byte.
+     */
+    applySurgicalReplace(target: string, newContent: string, meta: {
+        runId: string;
+        reason: 'str_replace' | 'todo_write' | 'subagent';
+        actorId: string;
+    }): Promise<{
+        ok: true;
+        path: string;
+        bytes: number;
+    }>;
+    /**
+     * Remove any staged write older than `ttlMs`. Returns the number
+     * of entries removed. Designed to be cheap at run start
+     * (typically <2ms for a few hundred entries).
+     */
+    gc(now?: number): number;
+    /**
+     * Sweep every run-id directory under `<cwd>/.fixo/staging/`.
+     * Returns the total number of expired entries removed. Called
+     * automatically at the start of every streaming run and is also
+     * exposed via the `/fixo gc` slash command.
+     */
+    static garbageCollectAll(cwd: string, ttlMs?: number): number;
+    /**
+     * Discard every staged write for the given (cwd, runId) pair. Used
+     * when an agent is force-killed (e.g. loop-trap hard-abort) so the
+     * workspace is left in its pre-run state. Returns the number of
+     * entries removed.
+     *
+     * Best-effort: a failure to remove a single entry is logged and
+     * swallowed so the caller never sees an exception from cleanup.
+     */
+    static rollbackAll(cwd: string, runId: string): number;
+}
+//# sourceMappingURL=staging.d.ts.map

package/dist/runtime/staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../src/runtime/staging.ts"],"names":[],"mappings":"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"}