@nuasite/cms-sidecar 0.43.0-beta.1

package/dist/types/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/types/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}

package/dist/types/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env bun
+import { createCmsCore, createNodeFs } from '@nuasite/cms-core';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { mediaFromEnv } from './media-from-env';
+import { createServer } from './server';
+/** Resolve the installed `@nuasite/cms-core` version for the capabilities/health payload. */
+function resolveCoreVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkg = require('@nuasite/cms-core/package.json');
+        if (pkg && typeof pkg === 'object' && 'version' in pkg && typeof pkg.version === 'string') {
+            return pkg.version;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return '0.0.0';
+}
+/** Read `--<name> <value>` (or `--<name>=<value>`) from argv. */
+function readFlag(args, name) {
+    const eq = `--${name}=`;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === `--${name}`)
+            return args[i + 1];
+        if (arg.startsWith(eq))
+            return arg.slice(eq.length);
+    }
+    return undefined;
+}
+function parseServeArgs(args) {
+    const rawPort = readFlag(args, 'port');
+    const port = rawPort !== undefined ? Number.parseInt(rawPort, 10) : Number.NaN;
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error('serve requires a valid --port <0-65535>');
+    }
+    const rawRoot = readFlag(args, 'root');
+    const root = path.resolve(rawRoot ?? process.cwd());
+    const contentDir = readFlag(args, 'content-dir');
+    return { port, root, contentDir };
+}
+function printUsage() {
+    console.log('Usage: cms-sidecar serve --port <port> [--root <dir>] [--content-dir <dir>]');
+    console.log('');
+    console.log('Runs a thin HTTP server exposing @nuasite/cms-core over /cms/v1.');
+    console.log('Media adapter is selected by CMS_MEDIA_ADAPTER (contember|s3|local|none).');
+}
+function serve(args) {
+    const { port, root, contentDir } = parseServeArgs(args);
+    const fs = createNodeFs(root);
+    const media = mediaFromEnv();
+    const core = createCmsCore(fs, { contentDir, media: media.adapter });
+    const coreVersion = resolveCoreVersion();
+    const server = createServer({ core, fs, root, coreVersion, contentDir });
+    const bunServer = Bun.serve({ port, fetch: server.fetch });
+    // Ready line — the contract with the F2 service runtime (`readyPattern`).
+    // Must match /cms-sidecar listening on .*:\d+/.
+    console.log(`cms-sidecar listening on :${bunServer.port}`);
+}
+const [, , command, ...args] = process.argv;
+switch (command) {
+    case 'serve':
+        serve(args);
+        break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+        printUsage();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        printUsage();
+        process.exit(1);
+}

package/dist/types/concurrency.d.ts

@@ -0,0 +1,26 @@
+import type { CmsFileSystem } from '@nuasite/cms-core';
+/**
+ * Hashing + per-file serialization for the sidecar layer.
+ *
+ * cms-core stays hash-agnostic: the optimistic-concurrency `baseHash`/`sourceHash`
+ * comparison and the in-process mutex live here. Hashing reads the on-disk source
+ * through the same `CmsFileSystem` port cms-core uses, so the hash reflects exactly
+ * the bytes a subsequent `getEntry` would parse.
+ */
+/** Stable content hash of a UTF-8 string: `sha256:<hex>`. */
+export declare function hashContent(content: string): string;
+/**
+ * Hash the current on-disk source at `sourcePath`, or `null` when the file does
+ * not exist. Reads via the port so the hash matches the bytes cms-core sees.
+ */
+export declare function hashSource(fs: CmsFileSystem, sourcePath: string): Promise<string | null>;
+/**
+ * Serializes async work keyed by a string (a source path). Concurrent mutations
+ * of the same entry run one-after-another; different entries run in parallel.
+ * The chain self-cleans: a key's tail is dropped once its last waiter settles.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    runExclusive<T>(key: string, task: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/types/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/concurrency.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAGtD;;;;;;;GAOG;AAEH,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAI9F;AAED;;;;GAIG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAEtD,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAetE"}

package/dist/types/concurrency.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+/**
+ * Hashing + per-file serialization for the sidecar layer.
+ *
+ * cms-core stays hash-agnostic: the optimistic-concurrency `baseHash`/`sourceHash`
+ * comparison and the in-process mutex live here. Hashing reads the on-disk source
+ * through the same `CmsFileSystem` port cms-core uses, so the hash reflects exactly
+ * the bytes a subsequent `getEntry` would parse.
+ */
+/** Stable content hash of a UTF-8 string: `sha256:<hex>`. */
+export function hashContent(content) {
+    return `sha256:${createHash('sha256').update(content, 'utf-8').digest('hex')}`;
+}
+/**
+ * Hash the current on-disk source at `sourcePath`, or `null` when the file does
+ * not exist. Reads via the port so the hash matches the bytes cms-core sees.
+ */
+export async function hashSource(fs, sourcePath) {
+    if (!(await fs.exists(sourcePath)))
+        return null;
+    const raw = await fs.readFile(sourcePath);
+    return hashContent(raw);
+}
+/**
+ * Serializes async work keyed by a string (a source path). Concurrent mutations
+ * of the same entry run one-after-another; different entries run in parallel.
+ * The chain self-cleans: a key's tail is dropped once its last waiter settles.
+ */
+export class KeyedMutex {
+    tails = new Map();
+    async runExclusive(key, task) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        // Chain after the previous holder, swallowing its result/rejection so one
+        // failed mutation never poisons the next waiter on the same key.
+        const run = previous.then(() => task(), () => task());
+        this.tails.set(key, run);
+        try {
+            return await run;
+        }
+        finally {
+            // Drop the entry only if no later waiter has chained onto it.
+            if (this.tails.get(key) === run) {
+                this.tails.delete(key);
+            }
+        }
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export { FIELD_TYPES, isFieldType } from '@nuasite/cms-types';
+export { hashContent, hashSource, KeyedMutex } from './concurrency';
+export { type MediaAdapterKind, mediaFromEnv, type MediaFromEnvResult } from './media-from-env';
+export { type CmsSidecarServer, createServer, type CreateServerOptions, SIDECAR_FEATURES } from './server';
+export type { AddArrayItemBody, ApiError, Capabilities, ConflictResponse, CreateEntryBody, CreateFolderBody, EntriesListResult, EntriesQuery, ErrorCode, PageEntry, ProjectModel, RemoveArrayItemBody, RenameEntryBody, UpdateEntryBody, } from './types';
+export { STATUS_BY_CODE } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,KAAK,gBAAgB,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC/F,OAAO,EAAE,KAAK,gBAAgB,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAC1G,YAAY,EACX,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,eAAe,GACf,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA"}

package/dist/types/index.js

@@ -0,0 +1,4 @@
+export { hashContent, hashSource, KeyedMutex } from './concurrency';
+export { mediaFromEnv } from './media-from-env';
+export { createServer, SIDECAR_FEATURES } from './server';
+export { STATUS_BY_CODE } from './types';

package/dist/types/media-from-env.d.ts

@@ -0,0 +1,32 @@
+import type { MediaStorageAdapter } from '@nuasite/cms-types';
+/**
+ * Pick the media storage adapter from the environment.
+ *
+ * `CMS_MEDIA_ADAPTER` selects the backend:
+ *   - `contember` (default): proxies to the Contember worker's CMS media API.
+ *       NUA_SITE_API_BASE_URL   — worker API base, e.g. https://api.example.com
+ *       NUA_SITE_PROJECT_SLUG   — project slug used in the media API path
+ *       NUA_SITE_SESSION_TOKEN  — session token (NUA_SITE_SESSION_TOKEN cookie value)
+ *   - `s3`: an S3-compatible bucket (needs the optional `@aws-sdk/client-s3` peer).
+ *       CMS_MEDIA_S3_BUCKET             — bucket name (required)
+ *       CMS_MEDIA_S3_REGION            — region (required)
+ *       CMS_MEDIA_S3_ACCESS_KEY_ID     — access key (optional; falls back to the SDK chain)
+ *       CMS_MEDIA_S3_SECRET_ACCESS_KEY — secret key (optional)
+ *       CMS_MEDIA_S3_ENDPOINT          — custom endpoint (optional, e.g. R2)
+ *       CMS_MEDIA_S3_CDN_PREFIX        — public CDN URL prefix (optional)
+ *       CMS_MEDIA_S3_PREFIX            — key prefix (optional, default 'uploads')
+ *   - `local`: filesystem under `public/uploads`.
+ *       CMS_MEDIA_LOCAL_DIR        — storage dir (optional, default 'public/uploads')
+ *       CMS_MEDIA_LOCAL_URL_PREFIX — served URL prefix (optional, default '/uploads')
+ *   - `none`: no media adapter (media routes answer 501 unsupported).
+ *
+ * Reads are confined to this module; the adapters themselves never touch
+ * `process.env`. Returns `undefined` when no adapter is configured.
+ */
+export type MediaAdapterKind = 'contember' | 's3' | 'local' | 'none';
+export interface MediaFromEnvResult {
+    kind: MediaAdapterKind;
+    adapter?: MediaStorageAdapter;
+}
+export declare function mediaFromEnv(env?: NodeJS.ProcessEnv): MediaFromEnvResult;
+//# sourceMappingURL=media-from-env.d.ts.map

package/dist/types/media-from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-from-env.d.ts","sourceRoot":"","sources":["../../src/media-from-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAE7D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,CAAA;AAQpE,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,gBAAgB,CAAA;IACtB,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAC7B;AAED,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAuDrF"}

package/dist/types/media-from-env.js

@@ -0,0 +1,57 @@
+import { createContemberStorageAdapter, createLocalStorageAdapter, createS3StorageAdapter, } from '@nuasite/cms-core';
+const VALID_KINDS = ['contember', 's3', 'local', 'none'];
+function isMediaAdapterKind(value) {
+    return VALID_KINDS.includes(value);
+}
+export function mediaFromEnv(env = process.env) {
+    const requested = env.CMS_MEDIA_ADAPTER?.trim().toLowerCase();
+    const kind = requested && isMediaAdapterKind(requested) ? requested : 'contember';
+    switch (kind) {
+        case 'none':
+            return { kind };
+        case 'local':
+            return {
+                kind,
+                adapter: createLocalStorageAdapter({
+                    dir: env.CMS_MEDIA_LOCAL_DIR,
+                    urlPrefix: env.CMS_MEDIA_LOCAL_URL_PREFIX,
+                }),
+            };
+        case 's3': {
+            const bucket = env.CMS_MEDIA_S3_BUCKET;
+            const region = env.CMS_MEDIA_S3_REGION;
+            if (!bucket || !region) {
+                throw new Error('CMS_MEDIA_ADAPTER=s3 requires CMS_MEDIA_S3_BUCKET and CMS_MEDIA_S3_REGION');
+            }
+            return {
+                kind,
+                adapter: createS3StorageAdapter({
+                    bucket,
+                    region,
+                    accessKeyId: env.CMS_MEDIA_S3_ACCESS_KEY_ID,
+                    secretAccessKey: env.CMS_MEDIA_S3_SECRET_ACCESS_KEY,
+                    endpoint: env.CMS_MEDIA_S3_ENDPOINT,
+                    cdnPrefix: env.CMS_MEDIA_S3_CDN_PREFIX,
+                    prefix: env.CMS_MEDIA_S3_PREFIX,
+                }),
+            };
+        }
+        case 'contember': {
+            const apiBaseUrl = env.NUA_SITE_API_BASE_URL;
+            const projectSlug = env.NUA_SITE_PROJECT_SLUG;
+            // Without the API base + project slug we cannot reach the worker; treat as
+            // "no media configured" rather than constructing a broken adapter.
+            if (!apiBaseUrl || !projectSlug) {
+                return { kind: 'none' };
+            }
+            return {
+                kind,
+                adapter: createContemberStorageAdapter({
+                    apiBaseUrl,
+                    projectSlug,
+                    sessionToken: env.NUA_SITE_SESSION_TOKEN,
+                }),
+            };
+        }
+    }
+}

package/dist/types/server.d.ts

@@ -0,0 +1,22 @@
+import type { CmsCore, CmsFileSystem } from '@nuasite/cms-core';
+/** Features the sidecar advertises so older/newer clients can degrade gracefully. */
+export declare const SIDECAR_FEATURES: readonly string[];
+export interface CreateServerOptions {
+    core: CmsCore;
+    /** The same `CmsFileSystem` port the core was built over — used for hashing and the page walk. */
+    fs: CmsFileSystem;
+    /** Resolved project root (absolute), surfaced in `/health`. */
+    root: string;
+    /** Version reported as `coreVersion` (the cms-core package version). */
+    coreVersion: string;
+    /** Content collections directory, relative to root. Defaults to `src/content`. */
+    contentDir?: string;
+    /** Max accepted upload size in bytes. Defaults to 20 MiB. */
+    maxUploadSize?: number;
+}
+export interface CmsSidecarServer {
+    /** The `fetch` handler — pass to `Bun.serve`, or drive directly in tests. */
+    fetch(req: Request): Promise<Response>;
+}
+export declare function createServer(opts: CreateServerOptions): CmsSidecarServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/types/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAqB/D,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAc7C,CAAA;AAMD,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,kGAAkG;IAClG,EAAE,EAAE,aAAa,CAAA;IACjB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAA;IACnB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AA+LD,MAAM,WAAW,gBAAgB;IAChC,6EAA6E;IAC7E,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CACtC;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CA+YxE"}