opencode-swarm 7.144.8 → 7.145.1

package/dist/utils/atomic-write.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Canonical atomic-write helper + temp-grammar registry (issue #2035).
+ *
+ * Single source of truth for:
+ *  - HOW production code atomically writes files under the project `.swarm/`
+ *    root: one same-directory write-temp→fsync→rename helper with exact
+ *    `finally` cleanup of its OWN temp only.
+ *  - WHAT temporary-file name grammars exist: a frozen registry derived from
+ *    the writer census so residue scanners classify candidates by exact
+ *    registered grammars instead of substring guesses.
+ *
+ * Why the registry lives here: every residue consumer (close clean stage,
+ * close dry-run, config doctor, diagnose, quarantine/rollback in
+ * `src/services/swarm-residue.ts`) must derive candidates from the SAME
+ * registered grammars, and every atomic writer must be classifiable against
+ * the same table (see `WRITER_CLASSIFICATION` and its ratchet test).
+ *
+ * Containment contract (issue #2035 req 1): the canonical target must live
+ * under a `.swarm/` root, determined by SPELLING — the nearest `.swarm` path
+ * segment between the filesystem root and the target. A pre-existing root
+ * must be a real directory (no symlinks), and no path segment between it and
+ * the target may be a symlink. Semantics are validateSwarmPath-INSPIRED but
+ * NOT identical — see the junction limitation on
+ * `assertSwarmContainedTarget`.
+ */
+import * as fs from 'node:fs';
+/**
+ * A registered temporary-file naming grammar.
+ *
+ * `match` is applied to the temp file's BASENAME only, case-sensitively —
+ * near-misses (unicode/case variants, trailing dots, ADS suffixes) must NOT
+ * match, so they are preserved untouched by every scanner.
+ */
+export interface SwarmTempGrammar {
+    /** Stable id used in reports, manifests, and telemetry (never renamed). */
+    readonly id: string;
+    readonly era: 'canonical' | 'current' | 'legacy';
+    /** Matches the temp basename. Capture group 1 = derivable target basename when `parsesTarget`. */
+    readonly match: RegExp;
+    /** The grammar embeds a per-invocation uniqueness token (ts/pid/uuid/random). */
+    readonly token: 'instance' | 'constant';
+    /** Trusted for quarantine when all eligibility gates pass (issue #2035 req 5). */
+    readonly quarantineEligible: boolean;
+    /** Whether a target basename can be parsed back out of the temp name. */
+    readonly parsesTarget: boolean;
+    /** Producing writer sites (file:line) — every known producer is listed. */
+    readonly producers: readonly string[];
+    /** Invariant reason the producer is NOT migrated to the canonical helper. */
+    readonly note?: string;
+}
+/**
+ * Every temp grammar a swarm writer has ever produced. Grammars marked
+ * `quarantineEligible: false` are constant-name temps: with no per-invocation
+ * token they are indistinguishable from an in-flight writer of ANY process or
+ * from an unrelated file, so scanners report them but never mutate them.
+ * ORDER MATTERS: `matchTempGrammar`/`parseTargetBasename` take the FIRST
+ * match, so more-specific grammars (uuid, two-token, .json-terminated) must
+ * be declared before the generic single-token family.
+ */
+export declare const SWARM_TEMP_GRAMMARS: readonly SwarmTempGrammar[];
+/** First registered grammar whose regex matches `basename`, or undefined. */
+export declare function matchTempGrammar(basename: string): SwarmTempGrammar | undefined;
+/**
+ * Parse the target basename a temp name was derived from (capture group 1).
+ * Returns null for prefix/leading-dot grammars with no derivable target.
+ */
+export declare function parseTargetBasename(basename: string): string | null;
+/**
+ * Structural classification of every file that constructs temp-file names
+ * (ratchet source for tests/unit/utils/atomic-write.test.ts — a new temp
+ * constructor must be classified here or the build fails):
+ *  - migrated:        writes through the canonical helper (registry lists its
+ *                     grammar only for historical residue discovery)
+ *  - registered-bespoke: keeps a dedicated writer with a documented invariant
+ *                     reason in the grammar `note` (issue #2035 req 2)
+ *  - external:        writes outside the `.swarm` containment boundary
+ *  - reader-only:     references temp names without constructing them
+ */
+export declare const WRITER_CLASSIFICATION: Readonly<Record<string, 'migrated' | 'registered-bespoke' | 'external' | 'reader-only'>>;
+/**
+ * Max depth considered when reasoning about `.swarm` path segments (advisory
+ * constant kept for diagnostics; containment itself is spelling-based).
+ */
+export declare const MAX_SWARM_ANCESTOR_DEPTH = 8;
+export interface SwarmContainment {
+    /** Project root that owns the `.swarm/` directory. */
+    projectRoot: string;
+    /** Canonical `.swarm/` directory containing the target. */
+    swarmRoot: string;
+}
+/**
+ * Reject obviously-invalid target spellings before any filesystem access:
+ * glob metacharacters, control chars/NUL, and unresolved environment-variable
+ * forms (`$VAR`, `%VAR%`, leading `~`). Quarantine/inventory paths and writer
+ * paths share this gate (issue #2035 req 7).
+ */
+export declare function assertWellFormedTargetPath(targetPath: string): void;
+/**
+ * Assert `targetPath` lives beneath a `.swarm/` root.
+ *
+ * The root is determined by SPELLING: the nearest `.swarm` path segment
+ * between the filesystem root and the target. Existence-based ancestor
+ * walking is deliberately avoided — a stray `.swarm` in an ancestor (e.g. the
+ * OS temp dir) would hijack the walk and reject legitimate first-writes whose
+ * own `.swarm` parent does not exist yet (invariant 4: ambiguous ancestor
+ * `.swarm` state fails closed). If the `.swarm` root exists it must be a real
+ * directory (no symlink), and no existing path segment between it and the
+ * target may be a symlink.
+ *
+ * KNOWN LIMITATION vs `validateSwarmPath` (src/hooks/utils.ts:157, PR review
+ * PRR-007): this check detects SYMLINKS via lstatSync().isSymbolicLink(),
+ * which returns FALSE for Windows directory JUNCTIONS (a distinct reparse
+ * class). validateSwarmPath resolves all reparse points via realpathSync. A
+ * junctioned `.swarm/` therefore passes this spelling-based gate. Mitigations
+ * in scope: junctions require same-user filesystem write access to create
+ * (outside the adversarial-local-process threat model invariant 4 excludes),
+ * targets are still spelling-bounded to the `.swarm` subtree, and the
+ * spell-time `.swarm` position must already exist in the user's path. Full
+ * junction parity would require realpath-resolution of every existing
+ * ancestor — deliberately out of budget for the write hot path.
+ *
+ * Project-boundary enforcement (`.git`/`.opencode` markers, invariant 4) is
+ * deliberately NOT re-checked here: that belongs to the tool-layer
+ * resolvers (`resolveWorkingDirectory`/`assertProjectRoot`), which have
+ * already validated the directory before any writer derived a target from
+ * it — validateSwarmPath applies the same split.
+ */
+export declare function assertSwarmContainedTarget(targetPath: string): SwarmContainment;
+/** Hard bound on a single atomic write (bounded-write requirement). */
+export declare const MAX_ATOMIC_WRITE_BYTES: number;
+export interface AtomicWriteOptions {
+    /** Skip the pre-rename fsync (tests / truly ephemeral data). */
+    readonly skipFsync?: boolean;
+    /**
+     * Override the bounded-write cap (default MAX_ATOMIC_WRITE_BYTES). Exposed
+     * so the bound itself is testable without allocating 256 MiB.
+     */
+    readonly maxBytes?: number;
+}
+/**
+ * Dependency-injection seam for failure-injection tests (repo convention;
+ * never mock.module — it leaks across bun:test files). Restore in afterEach.
+ *
+ * The defaults DELEGATE to the live `fs` namespace on every call (instead of
+ * capturing the function at module load) so sibling tests that patch
+ * `node:fs` via `mock.module` — while still calling through to the real
+ * implementation — observe these calls, matching the recording patterns in
+ * tests/unit/commands/atomic-writes.test.ts.
+ */
+export declare const _internals: {
+    randomSuffix: () => string;
+    writeSync: (fd: number, buffer: Uint8Array, offset: number, length: number) => number;
+    renameSync: (from: string, to: string) => ReturnType<typeof fs.renameSync>;
+    unlinkSync: (p: string) => ReturnType<typeof fs.unlinkSync>;
+    fsyncSync: (fd: number) => ReturnType<typeof fs.fsyncSync>;
+};
+/**
+ * Canonical atomic write under the project `.swarm/` root (issue #2035 req 1):
+ * contained target, unique non-predictable same-directory temp, bounded write,
+ * fsync+close where supported, platform-safe replace (bounded rename retry on
+ * Windows transient locks — never unlink-then-rename, which would break
+ * atomicity), and exact finally cleanup of this invocation's temp only.
+ *
+ * The payload is bounded (≤ MAX_ATOMIC_WRITE_BYTES), so the synchronous
+ * temp-write core is the same latency class as the previous per-caller
+ * write-temp implementations; the async signature preserves caller shapes.
+ */
+export declare function atomicWriteSwarmFile(targetPath: string, content: string | Uint8Array, options?: AtomicWriteOptions): Promise<void>;
+/** Synchronous variant of {@link atomicWriteSwarmFile} (same core). */
+export declare function atomicWriteSwarmFileSync(targetPath: string, content: string | Uint8Array, options?: AtomicWriteOptions): void;
+/**
+ * Canonical atomic write WITHOUT the `.swarm` containment requirement.
+ *
+ * Documented invariant reason this variant exists (issue #2035 req 2): the
+ * legacy shared writer `atomicWriteFile` (src/evidence/task-file.ts) serves
+ * DUAL destinations — `.swarm/evidence/**` files AND the linked/hive
+ * knowledge stores whose platform-data/link directories live OUTSIDE any
+ * `.swarm` root (src/hooks/knowledge-store.ts, knowledge-link.ts,
+ * memory-link.ts, family migrations). Those callers migrate to this variant
+ * so they still gain the canonical grammar, fsync, bounded retry, exact
+ * own-temp cleanup, and cache invalidation — everything except root
+ * containment, which their destinations make inapplicable. New `.swarm`
+ * callers MUST use {@link atomicWriteSwarmFile}.
+ */
+export declare function atomicWriteFileAnyRoot(targetPath: string, content: string | Uint8Array, options?: AtomicWriteOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.144.8",
+	"version": "7.145.1",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/dist/cli/guardrail-explain-hvtyr2fz.js

@@ -1,64 +0,0 @@
-// @bun
-import {
-  handleGuardrailExplain
-} from "./index-r2rkwvzq.js";
-import"./index-c2rpht77.js";
-import"./index-nmy6rss1.js";
-import"./index-r14qx363.js";
-import"./index-z4fssj97.js";
-import"./index-134d35c1.js";
-import"./index-abtrcs16.js";
-import"./index-6z5jtf7d.js";
-import"./index-wknz5c8q.js";
-import"./index-y8552snf.js";
-import"./index-d1dbpxxk.js";
-import"./index-70ha9e09.js";
-import"./index-c8s9a3zh.js";
-import"./index-9ss2m4rs.js";
-import"./index-f36ybbsv.js";
-import"./index-hkdgkkhb.js";
-import"./index-sxe5nyq4.js";
-import"./index-xx8tm58n.js";
-import"./index-8dbzaf0m.js";
-import"./index-vdha477y.js";
-import"./index-rtry5xyf.js";
-import"./index-zsrtt42s.js";
-import"./index-n4hwcsbd.js";
-import"./index-cwtpqm5f.js";
-import"./index-jdxnzbah.js";
-import"./index-xp5g9eps.js";
-import"./index-k7fk9fjs.js";
-import"./index-tffg4mwr.js";
-import"./index-556ja8an.js";
-import"./index-7sy3aa9m.js";
-import"./index-wx8zdh4a.js";
-import"./index-3g0xk6tk.js";
-import"./index-85gkedsf.js";
-import"./index-3k3nbs52.js";
-import"./index-cx51wy0c.js";
-import"./index-0v1f2sdb.js";
-import"./index-gprxjmm7.js";
-import"./index-n832052r.js";
-import"./index-fv0s19g9.js";
-import"./index-z6xqpmqg.js";
-import"./index-7qb0hn8n.js";
-import"./index-gfvkttvd.js";
-import"./index-v3y3qg48.js";
-import"./index-9e6fdz2h.js";
-import"./index-4rhhvd1a.js";
-import"./index-zjygnfay.js";
-import"./index-ae75rja9.js";
-import"./index-h1p08s3n.js";
-import"./index-9s8drsf9.js";
-import"./index-ed5ykebp.js";
-import"./index-bk5tah7q.js";
-import"./index-f9vvg5xb.js";
-import"./index-1jsmmx7y.js";
-import"./index-7g4c7s5r.js";
-import"./index-bpmtbmy9.js";
-import"./index-zj6t9zgx.js";
-import"./index-zgwm4ryv.js";
-import"./index-a76rekgs.js";
-export {
-  handleGuardrailExplain
-};

package/dist/cli/{index-fv0s19g9.js → index-w8pgjr75.js}

@@ -2,12 +2,12 @@
 import {
   SwarmError
 } from "./index-z6xqpmqg.js";
-import {
-  readCachedTextFile
-} from "./index-ed5ykebp.js";
 import {
   bunFile
 } from "./index-zj6t9zgx.js";
+import {
+  readCachedTextFile
+} from "./index-ed5ykebp.js";
 import {
   warn
 } from "./index-zgwm4ryv.js";