pulseed 0.6.4 → 0.6.6

package/dist/base/utils/json-io.d.ts

@@ -1,13 +1,37 @@
-import { z } from "zod";
+import type { z } from "zod";
 interface WriteJsonFileAtomicOptions {
     mode?: number;
     directoryMode?: number;
 }
+interface JsonFileMutationLockOptions {
+    timeoutMs?: number;
+    retryDelayMs?: number;
+}
+export interface ReadTextFileWithinLimitOptions {
+    maxBytes: number;
+    chunkBytes?: number;
+    encoding?: BufferEncoding;
+}
+export declare class TextFileSizeLimitError extends Error {
+    readonly filePath: string;
+    readonly maxBytes: number;
+    readonly code = "ERR_PULSEED_TEXT_FILE_SIZE_LIMIT";
+    constructor(filePath: string, maxBytes: number);
+}
+export declare function isTextFileSizeLimitError(err: unknown): err is TextFileSizeLimitError;
 /**
  * Write data to a JSON file atomically (write to a unique .tmp, then rename).
  * Creates parent directories as needed.
  */
 export declare function writeJsonFileAtomic(filePath: string, data: unknown, options?: WriteJsonFileAtomicOptions): Promise<void>;
+export declare function withJsonFileMutationLock<T>(filePath: string, operation: () => Promise<T>, options?: JsonFileMutationLockOptions): Promise<T>;
+/**
+ * Read a UTF-8 text file from a single opened descriptor while enforcing a byte cap.
+ * The implementation reads at most maxBytes + 1 bytes, so callers can reject
+ * oversized JSON before loading or parsing the whole file.
+ */
+export declare function readTextFileWithinLimit(filePath: string, options: ReadTextFileWithinLimitOptions): Promise<string>;
+export declare function readTextFileWithinLimitSync(filePath: string, options: ReadTextFileWithinLimitOptions): string;
 /**
  * Read and parse a JSON file asynchronously.
  * Returns null on ENOENT or invalid JSON (does not throw).

package/dist/base/utils/json-io.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-io.d.ts","sourceRoot":"","sources":["../../../src/base/utils/json-io.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,UAAU,0BAA0B;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOzF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAKnB;AAKD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGlE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF"}
+{"version":3,"file":"json-io.d.ts","sourceRoot":"","sources":["../../../src/base/utils/json-io.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,UAAU,0BAA0B;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,2BAA2B;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAI7C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAJ3B,QAAQ,CAAC,IAAI,sCAAsC;gBAGxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;CAK5B;AAID,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,sBAAsB,CAEpF;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,CAAC,CAAC,CA4BZ;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,8BAA8B,GACtC,MAAM,CAcR;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAezF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAKnB;AAKD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGlE;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF"}

package/dist/base/utils/json-io.js

@@ -4,8 +4,24 @@
 // Async versions (writeJsonFileAtomic, readJsonFileOrNull, readJsonFileWithSchema)
 // are preferred over the legacy sync-style async functions below.
 import * as fsp from "node:fs/promises";
+import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
+export class TextFileSizeLimitError extends Error {
+    filePath;
+    maxBytes;
+    code = "ERR_PULSEED_TEXT_FILE_SIZE_LIMIT";
+    constructor(filePath, maxBytes) {
+        super(`Refused to read ${filePath} because it exceeds ${maxBytes} bytes`);
+        this.filePath = filePath;
+        this.maxBytes = maxBytes;
+        this.name = "TextFileSizeLimitError";
+    }
+}
+const DEFAULT_BOUNDED_TEXT_READ_CHUNK_BYTES = 64 * 1024;
+export function isTextFileSizeLimitError(err) {
+    return err instanceof TextFileSizeLimitError;
+}
 /**
  * Write data to a JSON file atomically (write to a unique .tmp, then rename).
  * Creates parent directories as needed.
@@ -40,17 +56,88 @@ export async function writeJsonFileAtomic(filePath, data, options = {}) {
         throw err;
     }
 }
+export async function withJsonFileMutationLock(filePath, operation, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const retryDelayMs = options.retryDelayMs ?? 10;
+    const lockPath = `${filePath}.lock`;
+    const startedAt = Date.now();
+    await fsp.mkdir(dirname(filePath), { recursive: true });
+    let lockHandle;
+    while (!lockHandle) {
+        try {
+            lockHandle = await fsp.open(lockPath, "wx");
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new Error(`Timed out waiting for JSON mutation lock: ${lockPath}`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await lockHandle.close();
+        await fsp.unlink(lockPath).catch((err) => {
+            if (err.code !== "ENOENT")
+                throw err;
+        });
+    }
+}
+/**
+ * Read a UTF-8 text file from a single opened descriptor while enforcing a byte cap.
+ * The implementation reads at most maxBytes + 1 bytes, so callers can reject
+ * oversized JSON before loading or parsing the whole file.
+ */
+export async function readTextFileWithinLimit(filePath, options) {
+    const normalized = normalizeBoundedTextReadOptions(options);
+    const handle = await fsp.open(filePath, "r");
+    try {
+        const { chunks, totalBytes } = await readChunksWithinLimit(async (buffer, length) => {
+            const { bytesRead } = await handle.read(buffer, 0, length, null);
+            return bytesRead;
+        }, filePath, normalized.maxBytes, normalized.chunkBytes);
+        return Buffer.concat(chunks, totalBytes).toString(normalized.encoding);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function readTextFileWithinLimitSync(filePath, options) {
+    const normalized = normalizeBoundedTextReadOptions(options);
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const { chunks, totalBytes } = readChunksWithinLimitSync((buffer, length) => fs.readSync(fd, buffer, 0, length, null), filePath, normalized.maxBytes, normalized.chunkBytes);
+        return Buffer.concat(chunks, totalBytes).toString(normalized.encoding);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 /**
  * Read and parse a JSON file asynchronously.
  * Returns null on ENOENT or invalid JSON (does not throw).
  */
 export async function readJsonFileOrNull(filePath) {
+    let content;
+    try {
+        content = await fsp.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
     try {
-        const content = await fsp.readFile(filePath, "utf-8");
         return JSON.parse(content);
     }
-    catch {
-        return null;
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
     }
 }
 /**
@@ -82,4 +169,58 @@ export async function readJsonFile(filePath) {
 export async function writeJsonFile(filePath, data) {
     await fsp.writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
 }
+function normalizeBoundedTextReadOptions(options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0 || options.maxBytes >= Number.MAX_SAFE_INTEGER) {
+        throw new RangeError("maxBytes must be a nonnegative safe integer below Number.MAX_SAFE_INTEGER");
+    }
+    const chunkBytes = options.chunkBytes ?? DEFAULT_BOUNDED_TEXT_READ_CHUNK_BYTES;
+    if (!Number.isSafeInteger(chunkBytes) || chunkBytes <= 0) {
+        throw new RangeError("chunkBytes must be a positive safe integer");
+    }
+    return {
+        maxBytes: options.maxBytes,
+        chunkBytes,
+        encoding: options.encoding ?? "utf-8",
+    };
+}
+async function readChunksWithinLimit(read, filePath, maxBytes, chunkBytes) {
+    const chunks = [];
+    const buffer = Buffer.allocUnsafe(Math.min(chunkBytes, maxBytes + 1));
+    let totalBytes = 0;
+    while (true) {
+        const remainingBytes = maxBytes + 1 - totalBytes;
+        if (remainingBytes <= 0) {
+            throw new TextFileSizeLimitError(filePath, maxBytes);
+        }
+        const bytesRead = await read(buffer, Math.min(buffer.byteLength, remainingBytes));
+        if (bytesRead === 0)
+            break;
+        totalBytes += bytesRead;
+        if (totalBytes > maxBytes) {
+            throw new TextFileSizeLimitError(filePath, maxBytes);
+        }
+        chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+    }
+    return { chunks, totalBytes };
+}
+function readChunksWithinLimitSync(read, filePath, maxBytes, chunkBytes) {
+    const chunks = [];
+    const buffer = Buffer.allocUnsafe(Math.min(chunkBytes, maxBytes + 1));
+    let totalBytes = 0;
+    while (true) {
+        const remainingBytes = maxBytes + 1 - totalBytes;
+        if (remainingBytes <= 0) {
+            throw new TextFileSizeLimitError(filePath, maxBytes);
+        }
+        const bytesRead = read(buffer, Math.min(buffer.byteLength, remainingBytes));
+        if (bytesRead === 0)
+            break;
+        totalBytes += bytesRead;
+        if (totalBytes > maxBytes) {
+            throw new TextFileSizeLimitError(filePath, maxBytes);
+        }
+        chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+    }
+    return { chunks, totalBytes };
+}
 //# sourceMappingURL=json-io.js.map

package/dist/base/utils/json-io.js.map

@@ -1 +1 @@
-{"version":3,"file":"json-io.js","sourceRoot":"","sources":["../../../src/base/utils/json-io.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"json-io.js","sourceRoot":"","sources":["../../../src/base/utils/json-io.ts"],"names":[],"mappings":"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"}

package/dist/base/utils/package-metadata.d.ts

@@ -0,0 +1,10 @@
+export interface PackageMetadata {
+    name: string;
+    description: string;
+    scripts: Record<string, string>;
+    dependencies: Record<string, string>;
+}
+export declare function createEmptyPackageMetadata(): PackageMetadata;
+export declare function parsePackageMetadata(raw: string): PackageMetadata | null;
+export declare function formatNodePackageMetadataContext(metadata: PackageMetadata): string;
+//# sourceMappingURL=package-metadata.d.ts.map

package/dist/base/utils/package-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-metadata.d.ts","sourceRoot":"","sources":["../../../src/base/utils/package-metadata.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,wBAAgB,0BAA0B,IAAI,eAAe,CAE5D;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAqBxE;AAED,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAMlF"}

package/dist/base/utils/package-metadata.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+const PackageStringRecordSchema = z.record(z.string(), z.string());
+const PackageManifestShapeSchema = z.object({
+    name: z.unknown().optional(),
+    description: z.unknown().optional(),
+    scripts: z.unknown().optional(),
+    dependencies: z.unknown().optional(),
+}).passthrough();
+export function createEmptyPackageMetadata() {
+    return { name: "", description: "", scripts: {}, dependencies: {} };
+}
+export function parsePackageMetadata(raw) {
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const manifest = PackageManifestShapeSchema.safeParse(decoded);
+    if (!manifest.success) {
+        return null;
+    }
+    const scripts = PackageStringRecordSchema.safeParse(manifest.data.scripts);
+    const dependencies = PackageStringRecordSchema.safeParse(manifest.data.dependencies);
+    return {
+        name: typeof manifest.data.name === "string" ? manifest.data.name : "",
+        description: typeof manifest.data.description === "string" ? manifest.data.description : "",
+        scripts: scripts.success ? scripts.data : {},
+        dependencies: dependencies.success ? dependencies.data : {},
+    };
+}
+export function formatNodePackageMetadataContext(metadata) {
+    const scripts = Object.keys(metadata.scripts).join(", ");
+    const prefix = metadata.name ? `Node.js project '${metadata.name}'` : "Node.js project";
+    const description = metadata.description ? `. ${metadata.description}` : "";
+    const scriptsPart = scripts ? `. Scripts: ${scripts}` : "";
+    return `${prefix}${description}${scriptsPart}`;
+}
+//# sourceMappingURL=package-metadata.js.map

package/dist/base/utils/package-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-metadata.js","sourceRoot":"","sources":["../../../src/base/utils/package-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACnE,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC5B,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACnC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,YAAY,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC,WAAW,EAAE,CAAC;AASjB,MAAM,UAAU,0BAA0B;IACxC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC;AACtE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,0BAA0B,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/D,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,yBAAyB,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3E,MAAM,YAAY,GAAG,yBAAyB,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACrF,OAAO;QACL,IAAI,EAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QACtE,WAAW,EAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE;QAC3F,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;QAC5C,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;KAC5D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,QAAyB;IACxE,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,iBAAiB,CAAC;IACxF,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,OAAO,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,EAAE,CAAC;AACjD,CAAC"}

package/dist/base/utils/paths.d.ts

@@ -3,8 +3,15 @@
  * Defaults to ~/.pulseed; can be overridden via PULSEED_HOME env var.
  */
 export declare function getPulseedDirPath(): string;
+/**
+ * Returns the default PulSeed-managed mutable workspace root.
+ * PULSEED_WORKSPACE_ROOT overrides the default ~/PulSeedWorkspaces location.
+ */
+export declare function getDefaultPulseedWorkspaceRootPath(): string;
 export declare function getGoalsDir(base?: string): string;
 export declare function getEventsDir(base?: string): string;
+export declare function getStateDir(base?: string): string;
+export declare function getControlDatabasePath(base?: string): string;
 export declare function getArchiveDir(base?: string): string;
 export declare function getPluginsDir(base?: string): string;
 export declare function getPromotedPluginsDir(base?: string): string;

package/dist/base/utils/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/base/utils/paths.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/base/utils/paths.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,IAAI,MAAM,CAE3D;AAED,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,aAAa,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/base/utils/paths.js

@@ -11,12 +11,25 @@ import * as path from "node:path";
 export function getPulseedDirPath() {
     return process.env["PULSEED_HOME"] ?? path.join(os.homedir(), ".pulseed");
 }
+/**
+ * Returns the default PulSeed-managed mutable workspace root.
+ * PULSEED_WORKSPACE_ROOT overrides the default ~/PulSeedWorkspaces location.
+ */
+export function getDefaultPulseedWorkspaceRootPath() {
+    return process.env["PULSEED_WORKSPACE_ROOT"] ?? path.join(os.homedir(), "PulSeedWorkspaces");
+}
 export function getGoalsDir(base) {
     return path.join(base ?? getPulseedDirPath(), "goals");
 }
 export function getEventsDir(base) {
     return path.join(base ?? getPulseedDirPath(), "events");
 }
+export function getStateDir(base) {
+    return path.join(base ?? getPulseedDirPath(), "state");
+}
+export function getControlDatabasePath(base) {
+    return path.join(getStateDir(base), "pulseed-control.sqlite");
+}
 export function getArchiveDir(base) {
     return path.join(base ?? getPulseedDirPath(), "archive");
 }

package/dist/base/utils/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/base/utils/paths.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,4CAA4C;AAC5C,kEAAkE;AAElE,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,0BAA0B,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAa;IACjD,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,IAAa;IACrE,OAAO,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,MAAM,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,aAAa,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,UAAU,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,iBAAiB,EAAE,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/base/utils/paths.ts"],"names":[],"mappings":"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"}

package/dist/base/utils/process-pid.d.ts

@@ -0,0 +1,15 @@
+export declare function isProcessPidValue(value: unknown): value is number;
+export declare function parseProcessPid(raw: string): number | null;
+export type ProcessSignalResult = {
+    status: "sent";
+    pid: number;
+} | {
+    status: "unsafe_pid";
+} | {
+    status: "missing_process";
+    pid: number;
+};
+export type ProcessSignal = NodeJS.Signals | 0;
+export declare function signalProcessPid(pid: unknown, signal: ProcessSignal): ProcessSignalResult;
+export declare function signalProcessGroup(pid: unknown, signal: NodeJS.Signals): ProcessSignalResult;
+//# sourceMappingURL=process-pid.d.ts.map

package/dist/base/utils/process-pid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-pid.d.ts","sourceRoot":"","sources":["../../../src/base/utils/process-pid.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEjE;AAMD,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM1D;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;AAE/C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,GAAG,mBAAmB,CAMzF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,mBAAmB,CAM5F"}

package/dist/base/utils/process-pid.js

@@ -0,0 +1,45 @@
+const PROCESS_PID_TOKEN = /^[0-9]+$/;
+export function isProcessPidValue(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isProcessGroupLeaderPidValue(value) {
+    return isProcessPidValue(value) && value > 1;
+}
+export function parseProcessPid(raw) {
+    const normalized = raw.trim();
+    if (!PROCESS_PID_TOKEN.test(normalized))
+        return null;
+    const pid = Number(normalized);
+    if (!isProcessPidValue(pid))
+        return null;
+    return pid;
+}
+export function signalProcessPid(pid, signal) {
+    if (!isProcessPidValue(pid)) {
+        return { status: "unsafe_pid" };
+    }
+    return signalCheckedPid(pid, signal, pid);
+}
+export function signalProcessGroup(pid, signal) {
+    if (!isProcessGroupLeaderPidValue(pid)) {
+        return { status: "unsafe_pid" };
+    }
+    return signalCheckedPid(-pid, signal, pid);
+}
+function signalCheckedPid(signalTarget, signal, pid) {
+    try {
+        process.kill(signalTarget, signal);
+        return { status: "sent", pid };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH") {
+            return { status: "missing_process", pid };
+        }
+        if (signal === 0 && code === "EPERM") {
+            return { status: "sent", pid };
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=process-pid.js.map

package/dist/base/utils/process-pid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-pid.js","sourceRoot":"","sources":["../../../src/base/utils/process-pid.ts"],"names":[],"mappings":"AAAA,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAErC,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC/E,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAc;IAClD,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,GAAG,CAAC;AACb,CAAC;AASD,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,MAAqB;IAClE,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAClC,CAAC;IAED,OAAO,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAY,EAAE,MAAsB;IACrE,IAAI,CAAC,4BAA4B,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAClC,CAAC;IAED,OAAO,gBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,gBAAgB,CACvB,YAAoB,EACpB,MAAqB,EACrB,GAAW;IAEX,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACnC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACjC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrB,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,CAAC;QAC5C,CAAC;QACD,IAAI,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACrC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QACjC,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/base/utils/usage-counter.d.ts

@@ -0,0 +1,14 @@
+export interface UsageCounter {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export declare function parseUsageTokenCount(value: unknown): number | null;
+export declare function zeroUsageCounter(): UsageCounter;
+export declare function addUsageTokenCounts(left: unknown, right: unknown): number;
+export declare function normalizeUsageCounter(raw: unknown): UsageCounter;
+export declare function sumUsageCounters(base: unknown, delta: unknown): UsageCounter;
+export declare function addUsageCounter(target: UsageCounter, delta: unknown): void;
+export declare function hasUsage(raw: unknown): boolean;
+export declare function formatUsageCounter(prefix: string, raw: unknown): string[];
+//# sourceMappingURL=usage-counter.d.ts.map

package/dist/base/utils/usage-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-counter.d.ts","sourceRoot":"","sources":["../../../src/base/utils/usage-counter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAElE;AAED,wBAAgB,gBAAgB,IAAI,YAAY,CAE/C;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAOhE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAQ5E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAK1E;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG9C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAOzE"}

package/dist/base/utils/usage-counter.js

@@ -0,0 +1,50 @@
+const MAX_TOKEN_COUNT = Number.MAX_SAFE_INTEGER;
+export function parseUsageTokenCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+export function zeroUsageCounter() {
+    return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+export function addUsageTokenCounts(left, right) {
+    const normalizedLeft = parseUsageTokenCount(left) ?? 0;
+    const normalizedRight = parseUsageTokenCount(right) ?? 0;
+    const sum = normalizedLeft + normalizedRight;
+    return Number.isSafeInteger(sum) ? sum : MAX_TOKEN_COUNT;
+}
+export function normalizeUsageCounter(raw) {
+    if (!raw || typeof raw !== "object")
+        return zeroUsageCounter();
+    const usage = raw;
+    const inputTokens = parseUsageTokenCount(usage.inputTokens) ?? 0;
+    const outputTokens = parseUsageTokenCount(usage.outputTokens) ?? 0;
+    const totalTokens = parseUsageTokenCount(usage.totalTokens) ?? addUsageTokenCounts(inputTokens, outputTokens);
+    return { inputTokens, outputTokens, totalTokens };
+}
+export function sumUsageCounters(base, delta) {
+    const normalizedBase = normalizeUsageCounter(base);
+    const normalizedDelta = normalizeUsageCounter(delta);
+    return {
+        inputTokens: addUsageTokenCounts(normalizedBase.inputTokens, normalizedDelta.inputTokens),
+        outputTokens: addUsageTokenCounts(normalizedBase.outputTokens, normalizedDelta.outputTokens),
+        totalTokens: addUsageTokenCounts(normalizedBase.totalTokens, normalizedDelta.totalTokens),
+    };
+}
+export function addUsageCounter(target, delta) {
+    const next = sumUsageCounters(target, delta);
+    target.inputTokens = next.inputTokens;
+    target.outputTokens = next.outputTokens;
+    target.totalTokens = next.totalTokens;
+}
+export function hasUsage(raw) {
+    const usage = normalizeUsageCounter(raw);
+    return usage.totalTokens > 0 || usage.inputTokens > 0 || usage.outputTokens > 0;
+}
+export function formatUsageCounter(prefix, raw) {
+    const usage = normalizeUsageCounter(raw);
+    return [
+        `${prefix} input tokens:  ${usage.inputTokens}`,
+        `${prefix} output tokens: ${usage.outputTokens}`,
+        `${prefix} total tokens:  ${usage.totalTokens}`,
+    ];
+}
+//# sourceMappingURL=usage-counter.js.map

package/dist/base/utils/usage-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-counter.js","sourceRoot":"","sources":["../../../src/base/utils/usage-counter.ts"],"names":[],"mappings":"AAMA,MAAM,eAAe,GAAG,MAAM,CAAC,gBAAgB,CAAC;AAEhD,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/F,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAa,EAAE,KAAc;IAC/D,MAAM,cAAc,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,eAAe,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzD,MAAM,GAAG,GAAG,cAAc,GAAG,eAAe,CAAC;IAC7C,OAAO,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,gBAAgB,EAAE,CAAC;IAC/D,MAAM,KAAK,GAAG,GAA8B,CAAC;IAC7C,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,YAAY,GAAG,oBAAoB,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACnE,MAAM,WAAW,GAAG,oBAAoB,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,mBAAmB,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC9G,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAa,EAAE,KAAc;IAC5D,MAAM,cAAc,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,eAAe,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IACrD,OAAO;QACL,WAAW,EAAE,mBAAmB,CAAC,cAAc,CAAC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC;QACzF,YAAY,EAAE,mBAAmB,CAAC,cAAc,CAAC,YAAY,EAAE,eAAe,CAAC,YAAY,CAAC;QAC5F,WAAW,EAAE,mBAAmB,CAAC,cAAc,CAAC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC;KAC1F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAoB,EAAE,KAAc;IAClE,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;IACtC,MAAM,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACxC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,MAAM,KAAK,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,CAAC,WAAW,GAAG,CAAC,IAAI,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,GAAY;IAC7D,MAAM,KAAK,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO;QACL,GAAG,MAAM,mBAAmB,KAAK,CAAC,WAAW,EAAE;QAC/C,GAAG,MAAM,mBAAmB,KAAK,CAAC,YAAY,EAAE;QAChD,GAAG,MAAM,mBAAmB,KAAK,CAAC,WAAW,EAAE;KAChD,CAAC;AACJ,CAAC"}

package/dist/base/utils/workspace-root.d.ts

@@ -0,0 +1,6 @@
+export declare function getPulseedWorkspaceRootPath(): string;
+export declare function workspaceRootRelativePath(absolutePath: string): string;
+export declare function assertOutsidePulSeedStateRoot(candidate: string, label: string): void;
+export declare function ensureDirectoryWithinWorkspaceRoot(dirPath: string): Promise<void>;
+export declare function isPathInsidePulSeedStateRoot(candidate: string): boolean;
+//# sourceMappingURL=workspace-root.d.ts.map

package/dist/base/utils/workspace-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-root.d.ts","sourceRoot":"","sources":["../../../src/base/utils/workspace-root.ts"],"names":[],"mappings":"AAMA,wBAAgB,2BAA2B,IAAI,MAAM,CAMpD;AAED,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAOtE;AAED,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAOpF;AAED,wBAAsB,kCAAkC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BvF;AAmBD,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAKvE"}

package/dist/base/utils/workspace-root.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { loadGlobalConfigSync } from "../config/global-config.js";
+import { getDefaultPulseedWorkspaceRootPath, getPulseedDirPath } from "./paths.js";
+export function getPulseedWorkspaceRootPath() {
+    if (process.env["PULSEED_WORKSPACE_ROOT"]) {
+        return path.resolve(process.env["PULSEED_WORKSPACE_ROOT"]);
+    }
+    const configured = loadGlobalConfigSync().workspace_root;
+    return path.resolve(configured || getDefaultPulseedWorkspaceRootPath());
+}
+export function workspaceRootRelativePath(absolutePath) {
+    const root = path.resolve(getPulseedWorkspaceRootPath());
+    const relativePath = path.relative(root, path.resolve(absolutePath));
+    if (relativePath === "" || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        throw new Error("path must stay within the PulSeed workspace root");
+    }
+    return relativePath.split(path.sep).join("/");
+}
+export function assertOutsidePulSeedStateRoot(candidate, label) {
+    const stateRoot = path.resolve(getPulseedDirPath());
+    const resolved = path.resolve(candidate);
+    const relativePath = path.relative(stateRoot, resolved);
+    if (resolved === stateRoot || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))) {
+        throw new Error(`${label} must be outside the protected PulSeed state root`);
+    }
+}
+export async function ensureDirectoryWithinWorkspaceRoot(dirPath) {
+    const workspaceRoot = path.resolve(getPulseedWorkspaceRootPath());
+    assertOutsidePulSeedStateRoot(workspaceRoot, "workspace_root");
+    await fs.mkdir(workspaceRoot, { recursive: true });
+    const realWorkspaceRoot = await fs.realpath(workspaceRoot);
+    assertWithin(workspaceRoot, dirPath, "directory");
+    const relativeParts = path.relative(workspaceRoot, path.resolve(dirPath)).split(path.sep).filter(Boolean);
+    let current = workspaceRoot;
+    for (const part of relativeParts) {
+        current = path.join(current, part);
+        const existingRealPath = await realpathOrNull(current);
+        if (existingRealPath) {
+            const stat = await fs.lstat(current);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`workspace path component must not be a symlink: ${workspaceRootRelativePath(current)}`);
+            }
+            assertWithin(realWorkspaceRoot, existingRealPath, "directory realpath");
+            if (!stat.isDirectory()) {
+                throw new Error(`workspace path component is not a directory: ${workspaceRootRelativePath(current)}`);
+            }
+            continue;
+        }
+        await fs.mkdir(current);
+        const createdRealPath = await fs.realpath(current);
+        assertWithin(realWorkspaceRoot, createdRealPath, "created directory");
+    }
+}
+function assertWithin(parent, candidate, label) {
+    const relativePath = path.relative(path.resolve(parent), path.resolve(candidate));
+    if (relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath))) {
+        return;
+    }
+    throw new Error(`${label} must stay within ${parent}`);
+}
+async function realpathOrNull(candidate) {
+    try {
+        return await fs.realpath(candidate);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export function isPathInsidePulSeedStateRoot(candidate) {
+    const stateRoot = canonicalPath(getPulseedDirPath());
+    const resolved = canonicalPath(candidate);
+    const relativePath = path.relative(stateRoot, resolved);
+    return resolved === stateRoot || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+function canonicalPath(value) {
+    try {
+        return fsSync.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+//# sourceMappingURL=workspace-root.js.map

package/dist/base/utils/workspace-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-root.js","sourceRoot":"","sources":["../../../src/base/utils/workspace-root.ts"],"names":[],"mappings":"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"}