@autokap/core 1.7.0 → 1.7.2

package/dist/fs-paths.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Sanitize a single path segment (NOT a full path — slashes are stripped) into
+ * a safe, deterministic filename token.
+ *
+ * - Collapses any run of characters outside `[A-Za-z0-9._-]` to a single `-`.
+ * - Collapses repeated `-`.
+ * - Trims leading/trailing `.`/`-`/space (Windows rejects trailing dot/space;
+ *   a leading dot would hide the file on POSIX).
+ * - Prefixes `_` when the result collides with a Windows reserved device name.
+ * - Caps length at 80 chars.
+ * - Falls back to `'artifact'` when nothing usable remains.
+ */
+export declare function sanitizePathToken(value: string): string;
+/**
+ * Resolve `fileName` inside `outputDir`, refusing any result that escapes the
+ * directory (via `..` segments or an absolute component). Returns the absolute
+ * contained path; throws otherwise.
+ *
+ * `fileName` should already be sanitized with `sanitizePathToken`; this is the
+ * defense-in-depth boundary check.
+ */
+export declare function resolveContainedPath(outputDir: string, fileName: string): string;
+/**
+ * Map an asset `format` token (`png`, `webp`, `gif`, `mp4`, …) to a file
+ * extension (without the leading dot). `jpeg` normalizes to `jpg`. Unknown
+ * formats fall back to `bin`.
+ */
+export declare function extFromFormat(format: string): string;
+/**
+ * Map a MIME type to a file extension (without the leading dot). Mirrors the
+ * mime→ext ladder previously inline in `cli-runner-local.ts`. Unknown types
+ * fall back to `bin`.
+ */
+export declare function extFromMimeType(mimeType: string): string;
+/**
+ * Atomically write `data` to `dest`: write to a per-process tmp sibling, then
+ * rename over the destination. A bare `writeFile` can be interrupted (crash,
+ * OOM, signal) mid-write, leaving a truncated file in the user's repo;
+ * tmp+rename is a single `rename(2)` syscall, atomic on POSIX (same volume)
+ * and on Windows NTFS.
+ *
+ * Unlike `~/.autokap` writes, this does NOT chmod — the destination is the
+ * user's project directory and should inherit normal umask permissions.
+ */
+export declare function writeFileAtomic(dest: string, data: Buffer): Promise<void>;

package/dist/fs-paths.js

@@ -0,0 +1,138 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+/**
+ * Shared filesystem-path helpers for the CLI and the MCP server.
+ *
+ * These were originally private to `src/cli-runner-local.ts` (CLI-only). The
+ * MCP download tools (`autokap_download_assets`) need the same path-safety and
+ * atomic-write guarantees when writing fetched assets into a user-chosen
+ * directory, so they live here in `@autokap/core` — imported by both surfaces.
+ *
+ * Cross-platform notes (CLAUDE.md §8):
+ *   - Always go through `path.*` (join/resolve/relative); never string-concat
+ *     with `/`.
+ *   - `sanitizePathToken` additionally guards Windows reserved device names and
+ *     trailing dots/spaces, which are illegal in NTFS filenames but harmless on
+ *     POSIX.
+ *   - `writeFileAtomic` deliberately does NOT chmod — downloads land in the
+ *     user's project directory (a repo `docs/images` dir), not a secrets dir,
+ *     so the restrictive 0o600 used for `~/.autokap/config.json` would be wrong.
+ */
+// Windows reserved device names (case-insensitive, with or without extension):
+// CON, PRN, AUX, NUL, COM1-9, LPT1-9. A file literally named `CON.png` is
+// rejected by the Win32 API, so we prefix an underscore to make it legal.
+const WINDOWS_RESERVED_NAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const MAX_PATH_TOKEN_LENGTH = 80;
+/**
+ * Sanitize a single path segment (NOT a full path — slashes are stripped) into
+ * a safe, deterministic filename token.
+ *
+ * - Collapses any run of characters outside `[A-Za-z0-9._-]` to a single `-`.
+ * - Collapses repeated `-`.
+ * - Trims leading/trailing `.`/`-`/space (Windows rejects trailing dot/space;
+ *   a leading dot would hide the file on POSIX).
+ * - Prefixes `_` when the result collides with a Windows reserved device name.
+ * - Caps length at 80 chars.
+ * - Falls back to `'artifact'` when nothing usable remains.
+ */
+export function sanitizePathToken(value) {
+    const cleaned = value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        // Strip leading/trailing dots, dashes and spaces. Leading `.` hides the
+        // file on POSIX; trailing `.`/space is silently dropped by Win32 (so two
+        // distinct tokens could collapse to the same on-disk name).
+        .replace(/^[.\-\s]+/, '')
+        .replace(/[.\-\s]+$/, '');
+    if (cleaned.length === 0) {
+        return 'artifact';
+    }
+    const capped = cleaned.slice(0, MAX_PATH_TOKEN_LENGTH);
+    // Re-trim after the slice — capping could have left a trailing `.`/`-`.
+    const trimmed = capped.replace(/[.\-\s]+$/, '');
+    const safe = trimmed.length > 0 ? trimmed : 'artifact';
+    if (WINDOWS_RESERVED_NAME_RE.test(safe)) {
+        return `_${safe}`;
+    }
+    return safe;
+}
+/**
+ * Resolve `fileName` inside `outputDir`, refusing any result that escapes the
+ * directory (via `..` segments or an absolute component). Returns the absolute
+ * contained path; throws otherwise.
+ *
+ * `fileName` should already be sanitized with `sanitizePathToken`; this is the
+ * defense-in-depth boundary check.
+ */
+export function resolveContainedPath(outputDir, fileName) {
+    const resolved = path.resolve(outputDir, fileName);
+    const relative = path.relative(outputDir, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Refusing to write outside output directory: ${fileName}`);
+    }
+    return resolved;
+}
+const FORMAT_EXTENSIONS = {
+    png: 'png',
+    jpg: 'jpg',
+    jpeg: 'jpg',
+    webp: 'webp',
+    gif: 'gif',
+    mp4: 'mp4',
+    webm: 'webm',
+};
+/**
+ * Map an asset `format` token (`png`, `webp`, `gif`, `mp4`, …) to a file
+ * extension (without the leading dot). `jpeg` normalizes to `jpg`. Unknown
+ * formats fall back to `bin`.
+ */
+export function extFromFormat(format) {
+    return FORMAT_EXTENSIONS[format.trim().toLowerCase()] ?? 'bin';
+}
+/**
+ * Map a MIME type to a file extension (without the leading dot). Mirrors the
+ * mime→ext ladder previously inline in `cli-runner-local.ts`. Unknown types
+ * fall back to `bin`.
+ */
+export function extFromMimeType(mimeType) {
+    const mime = mimeType.split(';', 1)[0].trim().toLowerCase();
+    switch (mime) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        case 'video/mp4':
+            return 'mp4';
+        case 'video/webm':
+            return 'webm';
+        default:
+            return 'bin';
+    }
+}
+/**
+ * Atomically write `data` to `dest`: write to a per-process tmp sibling, then
+ * rename over the destination. A bare `writeFile` can be interrupted (crash,
+ * OOM, signal) mid-write, leaving a truncated file in the user's repo;
+ * tmp+rename is a single `rename(2)` syscall, atomic on POSIX (same volume)
+ * and on Windows NTFS.
+ *
+ * Unlike `~/.autokap` writes, this does NOT chmod — the destination is the
+ * user's project directory and should inherit normal umask permissions.
+ */
+export async function writeFileAtomic(dest, data) {
+    const tmp = `${dest}.${process.pid}.${Date.now().toString(36)}.tmp`;
+    try {
+        await fs.writeFile(tmp, data);
+        await fs.rename(tmp, dest);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+//# sourceMappingURL=fs-paths.js.map

package/dist/index.d.ts

@@ -2,4 +2,5 @@ export * from './types.js';
 export * from './config.js';
 export * from './api-client.js';
 export * from './endpoint-helpers.js';
+export * from './fs-paths.js';
 export * from './logger.js';

package/dist/index.js

@@ -2,5 +2,6 @@ export * from './types.js';
 export * from './config.js';
 export * from './api-client.js';
 export * from './endpoint-helpers.js';
+export * from './fs-paths.js';
 export * from './logger.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autokap/core",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Shared core library for AutoKap CLI and MCP server",
   "license": "ISC",
   "author": "AutoKap",
@@ -33,6 +33,10 @@
       "types": "./dist/endpoint-helpers.d.ts",
       "default": "./dist/endpoint-helpers.js"
     },
+    "./fs-paths": {
+      "types": "./dist/fs-paths.d.ts",
+      "default": "./dist/fs-paths.js"
+    },
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"